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Chapter 16 


QuickDraw II 


Any time your desktop application needs to draw something, it uses QuickDraw n 
(and its extension, QuickDraw II Auxiliary). QuickDraw II is an adaptation and 
extension of the Macintosh toolbox component QuickDraw—^it performs similar 
operations but has been enhanced to support Apple IIGS color. 

QuickDraw II allows your application to 

■ Perform graphic operations easily and quickly 

■ Draw lines and shapes of various sizes and patterns 

■ Draw items in a variety of colors or gray scales 

■ Draw text in different fonts and with styling variations, such as italics and boldface 


A preview of the QuickDraw II routines 

To introduce you to the capabilities of QuickDraw II, all QuickDraw II routines are 
grouped by function and briefly described in Table 16-1. These routines are 
described in detail later in this chapter, where they are separated into housekeeping 
routines (discussed in routine number order) and the rest of the QuickDraw II 
routines (discussed in alphabetical order). 










TabI© 16-1 

QuickDraw II routines and their functions 


Routine Description 


Housekeeping routines 

QDBootInit Initializes QuickDraw 11; called only by the Tool Locator—must not be called by an 


QDStartUp 

QDShutDown 

QDVersion 

QDReset 

application 

Starts up QuickDraw II for use by an application 

Shuts down QuickDraw II when an application quits 

Returns the version number of QuickDraw II 

Resets QuickDraw II; called only when the system is reset—must not be called by an 
application 


QDStatus Indicates whether QuickDraw II is active 

Global environment routines 

GetStandardSCB Returns a copy of the standard scan line control byte (SCB) 


SetMasterSCB 

GetMasterSCB 

InitColorTable 

SetColorTable 

GetColorTable 

SetColorEntry 

GetColorEntry 

SetSCB 

GetSCB 

SetAllSCBs 

SetSysFont 

GetSysFont 

ClearScreen 

GrafOn 

GrafOff 

SetBufDims 

Sets the master SCB to a specified value 

Returns a copy of the master SCB 

Returns a copy of the standard color table for the current mode 

Sets a specified color table to specified values 

Fills a specified color table with the contents of another color table 

Sets the value of a color in a specified color table 

Returns the value of a specified color in a specified color table 

Sets the SCB to a specified value 

Returns the value of a specified SCB 

Sets all SCBs to a specified value 

Sets a specified font as the system font 

Returns a handle to the current system font 

Sets the words in screen memory to a specified value 

Turns on Super Hi-Res graphics mode 

Turns off Super Hi-Res graphics mode 

Sets the size of the QuickDraw II clipping and text buffers, padding the values to 
permit large values of chExtra and spExtra and to allow for style modifications 

ForceBufDims 

Sets the size of the QuickDraw II clipping and text buffers, but doesn't pad the values 
in any way 

SaveBufDims 

RestoreBufDims 

Saves QuickDraw IFs buffer-sizing information in an eight-byte record 

Restores QuickDraw IPs internal buffers to the sizes described in the eight-byte 
record created by the SaveBufDims routine 


16-2 


Chapter 16: QuickDraw II 




Table 16-1 (continued) 

QuickDraw II routines and their functions 


Routine Description 

GrafPort routines 

OpenPort Initializes specified memory locations as a standard GrafPort, allocates a new 

visible region and a new clipping region, and makes the GrafPort the current port 
InitPort Initializes specified memory locations as a standard port 

ClosePort Deallocates the clipping and visible regions in a port 

SetPort Makes a specified port the current GrafPort 

GetPort Returns a pointer to the current GrafPort 

SetPortLoc Sets the current port’s locinfo record to specified location information 

GetPortLoc Gets the current port’s locinfo record and puts it at the specified location 

SetPortRect Sets the current GrafPort’s port rectangle to the specified rectangle 

GetPortRect Returns the current GrafPort's port rectangle 

SetPortSize Changes the size of the current GrafPort’s port rectangle 

MovePortTo Changes the location of the current GrafPort’s port rectangle 

SetOrigin Adjusts the contents of the port reaangle and the bounds rectangle so the upper 

left corner of the port rectangle is set to the specified point 
SetClip Copies a specified region into the clipping region 

GetClip Copies the clipping region to a specified region 

ClipRect Changes the dipping region of the current GrafPort to a rectangle that is equivalent 

to a spedfied rectangle 
Pen and pattern routines 

HidePen Decrements the pen level 

ShowPen Increments the pen level 

GetPen Returns the pen location 

SetPenState Sets the pen state in the GrafPort to specified values 

GetPenState Returns the pen state from the GrafPort to a spedfied location 

SetPenSize Sets the current pen size to a spedfied pen size 

GetPenSize Returns the current pen size to a spedfied location 

SetPenMode Sets the current pen mode to a spedfied pen mode 

GetPenMode Returns the pen mode from the current GrafPort 

SetPenPat Sets the current pen pattern to a spedfied pen pattern 

GetPenPat Copies the current pen pattern from the current GrafPort to a spedfied location 

SetSolidPenPat Sets the pen pattern to a solid pattern using the specified color 

SetPenMask Sets the pen mask to a specified mask 

GetPenMask Returns the pen mask to a specified location 

SetBackPat Sets the background pattern to a spedfied pattern 

GetBackPat Copies the current background pen pattern from the current GrafPort to a spedfied 

location 

SetSolidBackPat Sets the background pattern to a solid pattern using a spedfied color 
SolidPattern Sets a spedfied pattern to a solid pattern using a spedfied color 

PenNormal Sets the pen state to the standard state; pen location is not changed 

MoveTo Moves the current pen location to a spedfied point 

Move Moves the current pen location by specified horizontal and vertical displacements 

(continued) 
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Table 16-1 (continued) 

QuickDraw II routines and their functions 


Routine 

Description 

Font routines 
SetFont 

GetFont 

GetRomFont 

SetFontID 

GetFontID 

GetFontInfo 

GetFGSize 

GetFontGlobals 

SetFontFlags 

GetFontFlags 

SetTextFace 

GetTextFace 

SetTextMode 

GetTextMode 

SetSpaceExtra 

GetSpaceExtra 

SetCharExtra 

GetCharExtra 

SetForeColor 

GetForeColor 

SetBackColor 

Sets the current font to a specified font 

Returns a handle to the current font 

Fills a specified buffer with information about the font in ROM 

Sets the fontID field in the GrafPort 

Returns the fontID field of the GrafPort 

Returns information about the current font in a specified record 

Returns the size of the font globals record 

Returns information about the current font in a specified record 

Sets the font flags word to a specified value 

Returns the current font flags word 

Sets the text face to a specified value 

Returns the current text face 

Sets the text mode to a specified value 

Returns the current text mode 

Sets the spExtra field in the GrafPort to a specified value 

Returns the value of the spExtra field from the GrafPort 

Sets the chExtra field in the GrafPort to a specified value 

Returns the chExtra field from the GrafPort 

Sets the ^Co/or field (foreground color) in the GrafPort to a specified value 

Returns the value of the current ^Cotor field (foreground color) from the GrafPort 
Sets the ijgCo/or field (background color) in the GrafPort to a specified value 


GetBackColor Returns the value of the current fc|gCo/or field (background color) from the GrafPort 
Miscellaneous GrafPorl routines 

SetClipHandle Sets the clipRgn handle field in the GrafPort to a specified value 


GetClipHandle 

SetVisRgn 

Returns a copy of the handle to the clipping region 

Copies a specified region into the visible region (but does not change the visRgn 
field of the GrafPort) 

GetVisRgn 

SetVisHandle 

GetVisHandle 

SetPicSave 

GetPicSave 

SetRgnSave 

GetRgnSave 

SetPolySave 

GetPolySave 

SetGrafProcs 

GetGrafProcs 

SetUserField 

GetUserField 

SetSysField 

Copies the contents of the visible region into a specified region 

Sets the visRgn field in the GrafPort to a specified value 

Returns a copy of the handle to the visible region 

Sets the picSave field in the GrafPort to a specified value 

Returns the value of the picSave field of the GrafPort 

Sets the rgnSave field in ^e GrafPort to a specified value 

Returns the value of the rgnSave field of the GrafPort 

Sets the polySave field in the GrafPort to a specified value 

Returns the value of the polySave field of the GrafPort 

Sets the graJProcs field of the current GrafPort to a specified value 

Returns the pointer to the graJProcs record associated with the GrafPort 

Sets the iiserField field in the GrafPort to a specified value 

Returns the value of the userField field of the GrafPort 

Sets the sysField field in the GrafPort to a specified value—must not be called by an 
application 


GetSysField Returns the value of the sysField field of the GrafPort 
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Table 16-1 (continued) 

QuickDraw il routines and their functions 


Routine Description 


Line drawing routines 

LineTo Draws a line from the current pen location to a specified point 

Line Draws a line from the current pen location to a new point specified by the 

horizontal and vertical displacements 

Rectangle drawing routines 

FrameRect Draws the frame of a specified rectangle using the current pen mode, pen pattern, 


PaintRect 

and pen size 

Paints the interior of a specified rectangle using the current pen mode and pen 

EraseRect 

InvertRect 

pattern 

Erases the interior of a specified rectangle by filling it with the background pattern 
Inverts the pixels in the interior of a specified rectangle 


FillRect Fills the interior of a specified rectangle with a specified pen pattern 

Round rectangle drawing routines 

FrameRRect Draws the frame of a specified round rectangle using the current pen mode, pen 


PaintRRect 

pattern, and pen size 

Paints the interior of a specified round rectangle using the current pen mode and 

EraseRRect 

pen pattern 

Erases the interior of a specified round rectangle by filling it with the background 

InvertRRect 

pattern 

Inverts the pixels in the interior of a specified round rectangle 


FillRRect Fills the interior of a specified round rectangle with a specified pen pattern 

Region drawing routines 

FrameRgn Draws the frame of a specified region using the current pen mode, pen pattern, 


PaintRgn 

and pen size 

Paints the interior of a specified region using the current pen mode and pen 

EraseRgn 

InvertRgn 

pattern 

Erases the interior of a specified region by filling it with the backgound pattern 
Inverts the pixels in the interior of a specified region 


FillRgn Fills the interior of a specified region with a specified pen pattern 

Polygon drawing routines 

FramePoly Draws the frame of a specified polygon using the current pen mode, pen pattern. 


PaintPoly 

and pen size 

Paints the interior of a specified polygon using the current pen mode and pen 

ErasePoly 

InvertPoly 

FillPoly 

pattern 

Erases the interior of a specified polygon by filling it with the background pattern 
Inverts the pixels in the interior of a specified polygon 

Fills the interior of a specified polygon with a specified pen pattern 

(continued) 
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Table 16-1 (continued) 

QuickDraw 11 routines and their functions 

Routine Description 

Oval drawing routines 

FrameOval Draws the frame of a specified oval using the current pen mode, pen pattern, and 

pen size 

PaintOval Paints the interior of a specified oval using the current pen mode and pen pattern 

EraseOval Erases the interior of a specified oval by filling it with the background pattern 

InvertOval Inverts the pixels in the interior of a specified oval 

FillOval Fills the interior of a specified oval with a specified pen pattern 

Arc drawing routines 
FrameArc 

PaintArc 
EraseArc 
InvertArc 
FillArc 

Pixel transfer routines 

ScrollRect Shifts the pixels inside the intersection of a specified rectangle, visible region, 

clipping region, port rectangle, and bounds rectangle 
PaintPixels Transfers a region of pixels 

PPToPort Transfers pixels from a source pixel map to the current port and clips the pixels to 

the current visible region and clipping region 

Text drawing and measuring routines 

DrawChar Draws a specified character at the current pen location and updates the pen 

location 

DrawText Draws specified text at the current pen location and updates the pen location 

DrawString Draws a specified Pascal-type string at the current pen location and updates the 

pen location 

DrawCString Draws a specified C string at the current pen location and updates the pen location 

CharWidth Returns the character width, in pixels (pen displacement), of a specified character 

TextWidth Returns the character width, in pixels (pen displacement), of specified text 

StringWidth Returns the sum of all character widths, in pixels (pen displacements), of a 

specified Pascal-type string 

CStringWidth Returns the sum of all the character widths, in pixels (pen displacements), of a 
specified C string 

CharBounds Puts the character bounds rectangle of a specified character into a specified buffer 

TextBounds Puts the character bounds rectangle of specified text into a specified buffer 

StringBounds Puts the character bounds rectangle of a specified Pascal-type string into a 

specified buffer 

CStringBounds Puts the character bounds rectangle of a specified C string into a specified buffer 


Draws the frame of a specified arc using the current pen mode, pen pattern, and 
pen size 

Paints the interior of a specified arc using the current pen mode and pen pattern 
Erases the interior of a specified arc by filling it with the background pattern 
Inverts the pixels in the interior of a specified arc 
Fills the interior of a specified arc with a specified pen pattern 
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Table 16-1 (continued) 

QuickDraw II routines and their functions 


Routine Description 


Calculations with 

SetRect 

OffsetRect 

InsetRect 

SectRect 

UnionRect 

PtInRect 

Pt2Rect 

EqualRect 

NotEmptyRect 


rectangles 

Sets a specified rectangle to specified values 

Offsets a specified rectangle by specified displacements 

Insets a specified rectangle by specified displacements 

Calculates the intersection of two reaangles and places the intersection in a 

destination rectangle 

Calculates the smallest rectangle that contains both source rectangles and places 
the result in a destination rectangle 

Detects whether the pixel below and to the right of a specified point is in a specified 
rectangle 

Copies a specified point to the upper left corner of a specified rectangle and 
another point to the lower right corner of the rectangle 
Indicates whether two rectangles are equal 
Indicates whether a specified rectangle is not empty 


Calculations with 

AddPt 

SubPt 

SetPt 

EqualPt 

LocalToGlobal 

GlobalToLocal 


points 

Adds two specified points together and leaves the result in the destination point 
Subtracts the source point from the destination point and leaves the result in the 
destination point 

Sets a point to specified horizontal and vertical values 
Indicates whether two points are equal 

Converts a point from local coordinates to global coordinates 
Converts a point from global coordinates to local coordinates 


Calculations with 
NewRgn 

DisposeRgn 

CopyRgn 

SetEmptyRgn 

SetRectRgn 

RectRgn 

OpenRgn 

CloseRgn 

OffsetRgn 

InsetRgn 

SectRgn 


regions 

Allocates space for a new region and initializes it to an empty region—this is the 

only way to create a new region 

Deallocates the memory for a specified region 

Copies the region definition from one region to another 

Destroys previous region information by setting a specified region to an empty 

region 

Destroys previous region information by setting a specified region to a specified 
rectangle 

Destroys previous region information by setting a specified region to a specified 
rectangle 

Allocates temporary space and starts saving lines and framed shapes for later 
processing as a region definition 

Completes the region definition process started by an OpenRgn call 
Moves a region on the coordinate plane a specified distance 
Shrinks or expands a specified region 

Calculates the intersection of two regions and places the intersection in a 
destination region 

(continued) 
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Table 16-1 (continued) 

QuickDraw II routines and their functions 


Routine Description 


Calculations with regions 

UnionRgn Calculates the smallest region that contains every point that is in either source 


DiffRgn 

region and places the result in a destination region 

Calculates the difference of two regions and places the difference in a destination 

XorRgn 

region 

Calculates the difference between the union and the intersection of two regions and 

PtInRgn 

places the result in a destination region 

Checks to see whether the pixel below and to the right of a specified point is within a 
specified region 

RectInRgn 

EqualRgn 

Checks whether a specified rectangle intersects a specified region 

Indicates whether two regions are equal 


EmptyRgn Indicates whether a specified region is empty 

Calculations with polygons 

OpenPoly Returns a handle to a polygon data structure that will be updated by future LineTo 


ClosePoly 

KillPoly 

calls 

Completes the polygon definition process started with an OpenPoly call 

Disposes of a specified polygon 


OffsetPoly Offsets a specified polygon by specified horizontal and vertical displacements 

Mapping and scaling utilities 

MapPt Maps a specified point from a source rectangle to a destination rectangle 


MapRect 

MapRgn 

MapPoly 

Maps a specified rectangle from a source rectangle to a destination rectangle 

Maps a specified region from a source rectangle to a destination rectangle 

Maps a specified polygon from a source rectangle to a destination rectangle 


ScalePt Scales a specified point from a source rectangle to a destination rectangle 

Cursor-handling routines 


SetCursor 

GetCursorAdr 

HideCursor 

ShowCursor 

ObscureCursor 

Sets the cursor to an image passed in a specified cursor record 

Returns a pointer to the current cursor record 

Hides the cursor by decrementing the cursor level 

Shows the cursor by incrementing the cursor level 

Hides the cursor until the mouse moves 


InitCursor Reinitializes the cursor 

Miscellaneous QuickDraw II utilities 

Random Returns a pseudorandom number in the range -32768 to 32767 


SetRandSeed 

GetPixel 

GetAddress 

SetIntUse 

Sets the seed value for the random number generator 

Returns the pixel below and to the right of a specified point 

Returns a pointer to a specified table 

Indicates to the cursor drawing code whether the code should use scan line 
interrupts 

SetStdProcs 

Sets up a specified record of pointers for customiaing QuickDraw II operations 
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Drawing to the screen and elsewhere 

QuickDraw II can draw to the screen or to other parts of Apple IIGS memory. In fact, 
printing a document with the Print Manager involves using QuickDraw II to “draw"* 
your document into a memory buffer used by the Print Manager (see Chapter 15, 
“Print Manager,” in Volume 1). 

To get our bearings, we’ll first consider where QuickDraw II draws. Then we’ll briefly 
discuss how it draws, and finally look at what it draws. 


Where QuickDraw II draws 

The question of where QuickDraw II draws involves consideration of Apple IIGS 
memory (including screen memory) as well as QuickDraw IPs own internal 
representation of its drawing universe. These are the main concepts for you to 
remember: 

■ Drawings are stored in Apple IIGS memory as pixel images, ordered collections of 
bytes that represent rectangular arrays of pixels. Screen memory contains a 
special pixel image—its contents are displayed on the computer’s monitor. 

■ QuickDraw II draws its text and graphic objects on an abstract two-dimensional 
mathematical surface called the coordinate plane. Points on a plane are much 
easier to visualize and manipulate than addresses in memory. Locations on the 
QuickDraw II coordinate plane are related to pixel-image locations by specific 
location information supplied to QuickDraw II. 

■ QuickDraw II draws most objects within the context of graphic ports. A port is a 
complete drawing environment and defines, among other things, a specific part 
of memory and a specific reaangular area on the coordinate plane where drawing 
can occur. There can be many ports open at a time—^some for drawing to the 
screen, some for drawing to other parts of memory. Different ports’ drawing 
spaces may be separate from each other, or they may overlap. 

■ QuickDraw II can be made to clip, or constrain its drawing, to within limits of 
arbitrary size, shape, and location. 

■ By manipulating two independent sets of coordinates (global coordinates and 
local coordinates), an application can easily control both what gets drawn inside 
a port’s drawing space and where on the screen or other pixel image that drawing 
space appears. 


Drawing to the screen and elsewhere 
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Coordinate plane 

QuickDraw II locates every action it takes in terms of coordinates on a two- 
dimensional grid, as shown in Figure l6-l. The grid is QuickDraw n*s coordinate 
plane; coordinates on the plane are integers ranging from -16K to +16K in both the 
X and Y directions. The point (0,0), therefore, is in the middle of the grid Note 
also that grid values increase to the right and doumward on the plane; this is 
different from what you might be used to, but it is the direction and order in which 
video scan lines are drawn. 

Units on the grid are in terms of pixels. Thus a 10 x 10 square on the coordinate 
plane is equivalent to a rectangle 10 pixels by 10 pixels on the display screen (this 
would not be a square, of course, because Apple IIGS pixels are not square). Only a 
very small portion of the coordinate plane can be displayed on the screen at any one 
time—the plane is 32,000 pixels on a side, and the screen can show a maximum of 
640 pixels by 200 pixels at a time. The small black square near the center of the grid 
in Figure 16-1 shows the approximate size of the screen (in 320 mode) compared with 
the coordinate plane. 


Warning 

QuickDraw II must not be asked to draw outside the coordinate plane. 
Commands to draw outside this space will produce unpredictable results. They 
won't generate errors. 


❖ Macintosh programmers: This conceptual drawing space is not the same as that 
for QuickDraw on the Macintosh. On the Macintosh, the drawing space is 64K by 
64K pixels centered around 0,0, which makes the boundary coordinates 
-32K,-32K and 32K,32K. 
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Figure 16-1 

QuickDraw II coordinate plane 

To understand how QuickDraw II does its drawing, we need to consider how it 
represents some basic graphic elements. On the coordinate plane, grid lines are 
considered to be infinitely thin. A point is defined as the intersection of two grid 
lines, so it also has no dimensions. Pixels, on the other hand, have a definite size; 
they are thought of as falling between the lines of the grid. The smallest element 
QuickDraw II can draw is a pixel, so if it were to draw a point at the location (3,3) on 
the coordinate plane, it would have to draw a single pixel. But which one? The point 
is between four pixels. 
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QuickDraw defines the pixel corresponding to each point on the plane as the pixel 
immediately below and to the right of the point, as shown in Figure l6-2. 
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Figure 16-2 

Grid lines, a point, and a pixel on the coordinate plane 

Pixel images and the coordinate plane 

A pixel image is an area of memory that contains a graphic image. The image is 
organized as a rectangular grid of pixels occupying contiguous memory locations. 
Each pixel has a value that determines what color in the graphic image is associated 
with that pixel. 

❖ Macintosh programmers: QuickDraw IPs pixel images are similar to Macintosh 
QuickDraw’s bit images. The major difference is that a pixel is described by 
more than a single bit. 

QuickDraw II draws to the coordinate plane. However, the coordinate plane is really 
just an abstract concept. Inside the Apple IIGS, drawing actually occurs by modifying 
pixel images—that is, by modifying the contents of certain memory locations. In 
particular, drawing something visible on the screen involves modifying the pixel 
image corresponding to screen memory. 
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The data structure that ties the coordinate plane to memory is the locinfo (for 
location information) record. The locinfo record tells QuickDraw II where in 
memory to draw, how the pixel image in that part of memory is arranged, and what 
that image’s position on the coordinate plane is. The structure of the locinfo record 
definition is shown in Figure l6-3, and each field is described in more detail 
following the figure. 


Offset Field 


Word— Replica of scan line control byte 


Long— POINTER to first byte of pixel Image 


Word— INTEGER; width. In bytes, of each line In pixel Image 
(must be even multiple of 8) 


Four words— RECT data structure defining boundary rectangle 


Figure 16-3 

The locinfo record 



The fields are as foUows: 

■ The portSCB (a replica of the scan line control byte) tells QuickDraw II how many 
bits per pixel there are in this image—two for 640 mode, four for 320 mode. The 
scan line control byte and the differences between 640 mode and 320 mode are 
discussed further in the section “Drawing in Color” in this chapter. 

■ The ptrToPixImage field contains the image pointer; that is, the memory 
address of the image. It points to the first byte of the pixel image, which contains 
the first (upper leftmost) pixel. 

■ The uHdth field specifies the image width; that is, the width (in bytes, not pixels) 
of each line in the pixel image. QuickDraw II needs to know this so it can tell where 
each new row in the image starts. (The image width must be an even multiple of 
eight bytes.) 

■ The boundsRect (for boundary rectangle) is a RECJT data structure defining the 
rectangle that maps the pixel image onto the coordinate plane. The top left point 
in the rectangle corresponds to the first pixel in the image. The bottom right of 
the rectangle describes the extent of the pixel image (as far as QuickDraw II is 
concerned). 
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The image pointer, the image width, and the boundary rectangle defined by the 
boundsRect are shown in Figure l6-4. 



Entire grid represents 
pixel image In memory. 

Lower right 
= (29,15) 


Figure 16-4 

Pixel image and boundary rectangle 


❖ Note: Remember that what separates one pixel image from another is where in 
memory it is stored, not where on the QuickDraw II coordinate plane its 
boundary rectangle happens to be. You can think of each pixel image as having 
its own private copy of the entire coordinate plane to play with, so even if two 
pixel images have overlapping coordinate plane locations, there won’t be any 
conflict between them if they occupy completely different parts of computer 
memory. 


GrofPort, port rectangle, and clipping 

Most drawing takes place in conjunction with a data structure called a GrafPort (for 
graphic port). Each GrafPort contains a complete specification of a drawing 
environment, including the location information (Joclnfo record) described 
earlier. In addition to the location information, a GrafPort contains three other 
fields that restrict where drawing in a pixel image can take place: the port rectangle, 
clipping region, and visible region. 

The port rectangle (as specified by the portRect field in the GrafPort) is a reaangle 
on the coordinate plane. Any drawing through a GrafPort occurs only inside its port 
rectangle. When you look at a window on the screen in a desktop application, its 
interior (everything but its frame) corresponds to a port rectangle. Windows are 
described further in Chapter 25, “Window Manager.” 
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The port rectangle can coincide with the boundary rectangle, or it can be different. 
You can think of it as a movable opening that allows access to all or part of the pixel 
image. As Figure l6-5 shows, QuickDraw n can draw only where the boundary 
reaangle and port rectangle overlap. 


( 0 , 0 ) 



Figure 16-5 

Boundary rectangle/port rectangle intersection 

The clipping region (as specified by the clipRgn field in the GrafPort) is provided 
for an application to use. When a GrafPort is opened or initiali 2 ed, the clipping 
region is set to the entire coordinate plane (effectively preventing any clipping from 
occuring). The program can use the dipping region any way it wants. Drawing to a 
pixel image through a GrafPort occurs only inside the clipping region. 

The visible region (as spedfied by the visRgn field in the GrafPort) is normally 
maintained by the Window Manager. An application can have multiple windows on 
the screen, each one assodated with a GrafPort. Windows can overlap, and each 
port’s visible region represents the parts of the window that are visible. 

❖ Note: When using GrafPorts that are not assodated with windows, it is up to your 
application to maintain the visible region. When a GrafPort is opened or 
initialized, its visRgn field is set to be equal to the portRect field. It will stay that 
way until your program changes it. 

In summary, drawing occurs in a pixel image only in the intersection of the boundary 
rectangle, port rectangle, clipping region, and visible region. 
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Global and local coordinate systenns 

In QuickDraw IFs universe, everything is positioned in terms of coordinates on the 
plane. However, if you think of multiple open windows on the screen, you can see 
that there are at least two different ways in which you might want to locate objects: 

■ You may want to specify where windows appear on the screen (when they are 
moved, for example), 

■ You may want to specify where objects appear within windows (when scrolling, for 
example) independently of where on the screen the windows may be. 

The toolbox needs global coordinates whenever more than one GrafPort share the 
same pixel image; the global coordinates tell QuickDraw II exactly where every port 
rectangle is compared with every other one. The global coordinate system for each 
GrafPort is that in which the boundary rectangle for its pixel image has its origin at 
(0,0) on the coordinate plane. In QuickDraw II, the origin of a rectangle is its upper 
left corner. For drawing to the screen, you can think of global coordinates as screen 
coordinates, where the top left corner of the screen is the point (0,0). 

However, each port also has its own local coordinate system. For example, when 
drawing into a port, you can think in terms of distance from the port rectangle’s 
origin rather than the boundary rectangle’s origin. By defining the port rectangle as 
starting at (0,0), you can base all your drawing commands on distance in from the 
left edge and down from the top of the port rectangle. 

That’s convenient for drawing in a window, but local coordinates offer more 
convenience than that They aren’t constrained to a value of (0,0) for the port 
rectangle origin—you can set them to any coordinate-plane value. Why would you 
want to? Because of the way drawing commands work. 

Suppose you are using a window to display portions of a document that is larger than 
the port rectangle in size —a fairly common occurrence. You are using drawing 
commands that draw the entire document, and you know that’s no problem because 
the drawing will be automatically clipped to the port rectangle. But how do you 
control which part of the document shows through in your window? You do it by 
adjusting local coordinates. 
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For example, consider a document that has (0,0) as its origin. All QuickDraw IPs 
drawing commands are based on the current port^s local coordinate system. So if 
location (0,0) in your GrafPort*s local coordinates correspond to the port rectangle’s 
upper left corner, any time you draw your document into that port, its upper left 
corner will be displayed. If you define your local coordinates differently, different 
parts of your document will appear in the window. Thus, you can think of local 
coordinates as document coordinates—the upper left corner of the document that 
the port displays is the local coordinate origin—as shown in Figure l6-6. 


Port 

rectangle 


Size of 
document 
being drawn 
into port 


( 0 , 0 ) 




Figure 16-6 

Drawing different parts of a document by changing local coordinates 

❖ Note: When the local coordinates of a GrafPort are changed, the coordinates of 
the GrafPort’s boundary rectangle and visible region are similarly recalculated, 
so the port will not change its relative position on the screen or its relation to 
other open ports on the screen. 

However, when the local coordinates are changed, the GrafPort’s clipping region 
and pen location are not changed—that is, they would appear to shift right along 
with the image that is being viewed in the port It makes sense to have the p>en (which 
is used to modify the image being viewed) and the dipping region (which is used to 
mask off parts of the image being viewed) stay with the image. 
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How QuickDraw II draws 


The way QuickDraw II draws any of its objects depends on the drawing environment 
specified in the current GrafPort. Each GrafPort record includes location and 
dipping information (described earlier), information about the graphics pen 
(described next), information about any text that will be drawn (described in the 
section “Drawing Text” in this chapter), and other information, such as the patterns 
to draw with. 

Drawing pen 

Each open port has its own drawing pen. The pen controls where and how drawing 
(of bodi text and graphics) occurs. It has several characteristics (which can be set by 
the application) that control this. 

Pen location: The pen has a coordinate-plane location (in local coordinates). The 
pen location is used only for drawing lines and text—other shapes are drawn 
independently of pen location. 

Pen size: The pen is a rectangle that can have almost any width or height. Its default 
size is 1 X 1 (pixels). If either the width or the height is set to 0, the pen will not draw. 

Pen pattern: The pen pattern is a repeating array (eight pixels by eight pixels) that is 
used like ink in the pen. Wherever the pen draws, the pen pattern is drawn in the 
image. The pattern is always aligned with the coordinate plane so that adjacent areas 
of the same pattern drawn at different times will blend in a continuous manner. 

Background pattern: The background pattern is an array similar to the pen pattern. 
The process of erasing is that of drawing with the background pattern. 

Drawing mask: The drawing mask is an eight-bit by eight-bit pattern that is used to 
mask, or screen off, parts of the pattern as it is drawn. Only those pixels in the 
pattern aligned with an on (1) bit in the mask are drawn. Figure 16-7 shows how a 
mask affects drawing with a pattern. 
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8x8 pattern 


Repeated 
every 8 pixels 


8x8 

drawing mask 



8x8 pattern 
with mask applied 



Figure 16-7 

Drawing with pattern and mask 

Note that drawing with a mask in which every bit has the value 1 is like drawing with no 
mask at all—^all pen pixels are passed through to the image. Likewise, drawing with a 
mask that is all 0*s is like not drawing at all—^all pen pixds are blocked 

Pen mode: The pen mode specifies one of eight Boolean operations (modeCopy, 
notCopy, modeOr, notOR, modeXOR, notXOR, modeBIC, and notBIC) that 
determine how the pen pattern is to affect an existing image. When the pen draws, 
QuickDraw II compares pixels in the existing image with their corresponding pixels in 
the pattern and then uses the pen mode to determine the value of the resulting pixels. 
For example, with a pen mode of modeCopy, the existing pixels* values are 
ignored—a solid black line is black regardless of the image already on the plane. 

With a pen mode of notXOR, the bits in each pen pixel are inverted, then combined 
in an exclusive-OR operation with the bits in each corresponding existing pixel. 
Figure l6-8 shows a filled rectangle drawn over an existing circle, in both modeCopy 
and notXOR mode. 



COPY mode notXOR mode 

Figure 16-8 

How pen mode affects drawing 
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The uses for the different pen modes are shown in Table 16-2. For more detail on 
how to use the modes, see the section “SetPenMode” in this chapter. 

Table 16-2 

Pen modes 

Mode Description 


modeCopy, notCopy 


modeOR, notOR 


modeXOR, notXOR 


modeBIC, notBIC 


Copy source (or NOT source) to destination. The modeCopy mode is the 
typical drawing mode. For text, the fully colored text pixels (both foreground 
and background) are copied into the destination. 

Overlay (OR) source (or NOT source) and destination. Use modeOR to 
nondestructively overlay new images on top of existing images and notOR to 
overlay inverted images. For text, the fully colored text pixels (both 
foreground and backgrouncD are ORed with the destination. 

Exclusive-or (XOR) pen with destination. Use these modes for cursor drawing 
and rubber-banding. If an image is drawn using modeXOR, the appearance of 
the destination at the image location can be restored merely by drawing the 
image again in modeXOR For text, the fully colored text pixels (both 
foreground and background) are XORed with the destination. 

Bit Clear (BIC) pen with destination ((NOT pen) AND destination). Use this 
mode to explicitly erase (turn ofO pixels, often prior to overlaying another 
image. You can use notBIC to display the intersection of two images. For 
text, the fully colored text pixels (both foreground and background) are 
BICed with the destination. 


Basic drawing functions 

QuickDraw II draws lines using the current pen size, pen pattern, drawing mask, and 

pen mode. It draws other shapes (rectangles, rounded-corner rectangles, ovals, 

arcs, polygons, and regions) in five different ways: 

■ Framing uses the current pen size, pen pattern, drawing mask and pen mode to 
draw an outline of the shape. 

■ Painting uses the current pen pattern, drawing mask, and pen mode to fill the 
interior of the shape. 

■ Erasing uses the current background pattern and drawing mask to fill the interior 
of the shape. 

■ Inverting uses the drawing mask to invert the pixels in the interior of the shape. 

■ Filling uses a specified pattern and the drawing mask to fill the interior of the 
shape. 

QuickDraw II draws text as described in the section “Drawing Text” in this chapter. 
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What QuickDraw II draws 

QuickDraw II can draw a number of graphic objects into a pixel image. It draws text 
characters in a variety of monospaced and proportional fonts, with styling variations 
that include italics, boldface, underlining, outlining, and shadowing. It draws 
straight lines of any length, width, and pattern. It draws hollow or pattern-filled 
rectangles, circles, and polygons. It draws elliptical arcs and filled wedges, irregular 
shapes, and collections of shapes. It also draws pictures—combinations of these 
simple shapes. Figure l6-9 summarizes QuickDraw IPs graphic objects. 
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rounded-corner 
rectangles 
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Figuro 16-9 

What QuickDraw II draws 


Points and lines 

A point is represented mathematically by its Y and X coordinates—these are two 
integers. 


Important 

QuickDraw ll's data structure that defines a point has the vertical coordinate 
first; (y,x) rather than (x,y). 
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A Une is represented by its ends—two points, or four integers. Like a point, a line is 
infinitely thin. When drawing a line, QuickDraw II moves the top left comer of the 
pen along the mathematical trajectory from the current pen location to the 
destination location. The pen hangs below and to the right of the trajectory, as 
illustrated in Figure 16-10. 


Starting 
pen location 


Pen size and 
pattern 



Destination location 




The line as drawn 


Figure 16-10 
Drawing a line 

Before drawing a line, you can use QuickDraw II calls to set the current pen location 
and other characteristics, such as pen size, mode, and pattern. 

Rectangles 

A rectangle is also represented by two points—^its upper left and lower right corners. 
The borders of a rectangle are infinitely thin. Rectangles are fundamental to 
QuickDraw II; there are many functions for moving, sizing, and otherwise 
manipulating rectangles. 

The pixels associated with a rectangle are only those within the rectangle's bounding 
lines. Thus, the pixels immediately below and to the right of the bottom and right- 
hand lines of the rectangle are not part of it. 


Important 

QuickDraw ll's RECT data structure has coordinates In the following order: top, 
left, bottom, right. Thus, the defining coordinates for the rectangle In Figure 16-11 
are (1,2,7,6). This order may be different from what you are used to, but It Is 
consistent with the (y,x) ordering of points. 
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The rectangle Is 
defined by the points 
(1,2) and (7,6). 

It encloses 24 pixels. 


Figure 16-11 

Rectangle 

Rectangles may have square or rounded corners. The corners of rounded-corner 
rectangles (Figure 16-12) are sections of ovals (discussed next); they are specified 
by an oval height and an oval width. 



Figure 16-12 

Rounded-corner rectangle 

Circles, ovals, arcs, and wedges 

Ellipses and portions of ellipses form another class of shapes drawn by (QuickDraw II. 
An oval (Figure 16-13) is an ellipse; it is defined in the same way as a rectangle, with 
the exception that QuickDraw II is told to draw the ellipse enscribed within the 
rectangle rather than the rectangle itself. If the enclosing rectangle is a square, the 
resulting oval is a circle. 



Oval Drawing to the screen and elsewhere 
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❖ Pixel shape: Remember, Apple IIGS pixels are not square. A perfect circle (or 
square) on the screen will have unequal horizontal and vertical dimensions in 
terms of pixels. 

An arc (Figure 16-14) is a portion of an oval defined by the oval’s enclosing rectangle 
and by two angles (the beginning and the end of the arc) and measured clockwise 
from vertical. 

If an arc is painted, filled, inverted, or erased, it becomes a wedge; its fill pattern 
extends to the center of the enclosing rectangle, within the area defined by the 
beginning and ending angle lines. 



Polygons 

A polygon (Figure 16-15) is any sequence of connected lines. You define a polygon 
by moving the pen to the starting point of the polygon and drawing lines from there 
to the next point, from that point to the next, and so on. 



Figure 16-15 
Polygon 
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Polygons are not treated exactly the same as other closed shapes, such as rectangles. 
For example, when QuickDraw II draws (Jrames) a polygon, it draws outside the 
actual boundary of the polygon because the line-drawing routines draw below and to 
the right of the pen locations. When it paints, fills, inverts, or erases a polygon, 
however, the fill pattern stays within the boundary of the polygon. If the polygon's 
ending point isn’t the same as its starting point, QuickDraw II adds a lipe between 
them to complete the shape. 

Regions 

A region is another fundamental element of QuickDraw II, one that can be 
considerably more complex than a line or a rectangle. A region (Figure I 6 -I 6 ) is 
defined as a collection of shapes or lines (or other regions) whose outline is one or 
more closed loops. Your application can draw, erase, move, or manipulate regions 
the way it does any other QuickDraw n shapes. 

You can define regions by drawing lines, framing shapes, manipulating existing 
regions, and equating regions to rectangles or other regions. 

Regions are particularly important to the Window Manager, which must keep track of 
often irregularly shaped, noncontiguous portions of windows in order to know when 
to activate the windows or what parts of them to update. 



Figure 16-16 
Region 

Pictures 

A picture is a collection of QuickDraw II drawing commands. Its data structure 
consists of little more than the stored commands. QuickDraw II plays the commands 
back when the picture is reconstructed with a DrawPicture call. A complex 
mechanical drawing produced from an Apple IIGS drafting program might be saved 
as a single QuickDraw II picture. 

Pictures can be used to transfer data between applications via the Clipboard. See 
Chapter 20, “Scrap Manager.” 
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Drawing text 

QuickDraw II doesn’t draw only graphic images—it also does all text drawing for 
desktop applications. As an application writer, you can easily control the 
placement, size, style, font, and color of display text with QuickDraw II calls. 

Your program can provide QuickDraw II with text in the following formats: 

■ Character: A single ASCII character at a time 

■ Pascal string: A length byte followed by a sequence of ASCII characters 

■ C string: A sequence of ASCII characters terminated by a 0 byte ($00) 

■ Text block: A number of ASCII characters in a buffer, with the number specified 
separately 

QuickDraw II draws the text in the same format in which it receives it. It draws each 
character at the current pen location, with the current font, using the current text 
mode, with the current character style, and using the current foreground and 
background colors. After text is drawn, the pen position is updated. 

Simple text manipulation 

This section introduces the text concepts you will need to know about for most 
applications. For most applications, you won’t need to know anything more about 
fonts than is presented in this section. If you’re writing an application that lets the 
user choose from a selection of fonts, or if you’re developing an application that 
requites a specific font, you’ll also need to know about the Font Manager. See 
Chapter 8, “Font Manager,” in Volume 1. 

A font is a collection of graphical and numerical information representing a set of 
characters. The graphical part of the font is called the font strike and consists of all 
the images of the characters, placed one after another. (The font strike in a IIGS font 
is stored in a one-bit-per-pixel format.) By convention, no blank space is left 
between the character images in the font strike; when text is drawn, both the space left 
between characters and the positioning of characters are determined by several 
tables of numerical information that are also part of the font. For the precise format 
of a IIGS font, see the section “Font Definition” in this chapter. 

QuickDraw II always displays and measures text using the current font (whose handle 
is found in the fontHandle field of the current GrafPort). 

A font has a base line (a horizontal line that runs throught the font strike), an ascent 
(the number of rows of pixels of the font above the base line), and a descent (the 
number of rows below). Each character in a font has a character image (the piece 
of the font strike that represents the character, using a bit set to 1 to represent the 
character’s foreground pixels), a character origin (a point on the base line used to 
position the character with respect to the current pen position), and a character 
width (the number of pixels QuickDraw II will advance the pen position after it draws 
the character). 
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These concepts are illustrated in Figure 16-17. 


Character width 



Image width 


Figure 16-17 

Character 

When a character is drawn, it’s placed so its character origin coincides with the 
current pen position. The character image’s 1 bits, as mentioned, determine the 
foreground pixels. (The 0 bits of the character image are background pixels, but 
they are not the character’s only background pixels. The precise definition of 
badcground pixels is provided later in this section,) 

After the character is drawn, the pen is automatically advanced by the character 
width. The next character drawn will have its character origin at this new pen 
position (if the pen hasn’t been moved first). Characters drawn one after the other 
are thus strung out horizontally in the expected manner. 

For most characters in most fonts, the character image will lie between the old pen 
position and the new one. In fact, the new pen position will usually be several pixels 
to the right of the rightmost pixels of the character image-, this supplies the small 
amount of blank space between characters. However, some characters in some fonts 
may have foreground pixels that lie to the left of the old pen position or to the right of 
the new pen position (or both). This is called keming. When kerning occurs, the 
character images of adjacent characters (that is, characters drawn one after another) 
may possibly overlap. 
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The character bounds rectangle determines the extent of the background pixels of 
a character. The character bounds rectangle, relative to a current pen position and 
starting from the character origin, extends as follows: 

■ As far up as the font's ascent 

■ As far down as the font's descent 

■ As far left as the current (jold) pen position, or as far as the character's leftmost 
foreground pixel, whichever is farther left (it is the leftmost foreground pixel if the 
character kerns to the left) 

■ As far right as the subsequent inew) pen position, or as far as the character's 
rightmost foreground pixel, whichever is farther right (it is the rightmost 
foreground pixel if the character kerns to the righO 

Because pen positions are points, not pixels, the phrase as far left as the current pen 
position means that it includes the pixels immediately to the right of the current pen 
position. Similarly, as far right as the subsequent pen position means that it 
includes the pixels immediately to the left of the subsequent pen position. 

This defines the character bounds rectangle, as shown in Figure 16-18. 


Character bounds width 



Ascent line 

Character bounds 
rectangle 
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Descent line 


Figure 16-18 

Character bounds rectangle 


The character bounds rectangle contains all the foreground pixels of the character; 
that was the point of extending it as far as any kerning the charaaer does in either 
direction. The background pixels of a character are defined to be all pixels in the 
character bounds rectangle that are not foreground pixels. Thus, the background 
pixels include all the pixels corresponding to 0 bits in the character image; in 
addition, they generally include those pixels extending from the old pen position to 
the new. 
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When QuickDraw II draws a character—say, using the pen mode modeCopy, with a 
foreground color of red and a background color of green—the foreground pixels are 
colored red and the background pixels are colored green. Our definition ensures 
that the background will at least go from pen position to pen position and that it will 
go far enough so no kerning foreground pixels will extend beyond the background. 

The QuickDraw II routine CharBounds calculates the character bounds rectangle of a 
specified character in local coordinates based on the current pen position. Every 
pixel that could be affected by drawing the character is located inside the character 
bounds rectangle. This is different from the QuickDraw II call CharWidth, which 
simply returns the character width of a specified character—that is, the amount by 
which the pen position would be advanced if the character were drawn. The width of 
the character bounds rectangle is not the same thing as the character width; either 
one may be larger than the other, or one may even be 0 and the other nonzero. It is 
not necessary, however, that the widths be different, and for some characters, they 
may be the same. 

❖ Note: Neither CharBounds nor CharWidth actually draws the character. 

When QuickDraw II draws a string (whether a Pascal-type string, a C-type string, or a 
text block), it draws the individual characters of the string into an internal text buffer, 
advancing the position in the text buffer by the character width after each character 
and ORing the character images together whenever they overlap (as they may with 
kerning). Then the entire string is drawn into the destination pixel image, using the 
current text mode, foreground and background colors, and so on. The pen position 
is advanced by the sum of the character widths of all the characters in the string. 

The QuickDraw II routines StringWidth, CStringWidth, and TextWidth return the 
amount the pen would be advanced if the specified string or text were to be drawn; 
that is, they return the sum of the character widths of all the characters in the string or 
text. 

The (QuickDraw II routines StringBounds, CStringBounds, and TextBounds return the 
smallest rectangle that would enclose all the foreground and background pixels of the 
string if it were drawn; in effect, they return the string bounds rectangle* This is 
the same as the UnionRect of all the individual character bounds rectangles (if the 
characters were drawn one after another). 


Important 

The rectangle is not necessarily the same as the rectangle you would get If you 
strung out the character bounds rectangles one after another, with the right 
edge of each touching the left edge of the next. Because of kerning, the 
character bounds rectangles of characters In a string may overlap. 


❖ Note: Neither the bounds calls nor the width calls actually draw anything. 
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The bounds calls and width calls take into account any active style modifications, 
chExtra and spExtra values, and fontFlags settings that may affea either the area 
covered by foreground and background pixels or the amount the pen is advanced 
after text drawing. The QuickDraw II routine GetFontInfo takes into account the style 
modifications, but not the values of chExtra, spExtra, or fontFlags. The QuickDraw II 
routines GetFontLore and GetFontGlobals report on the current font as it exists in 
memory and do not take into account any of the other values mentioned. 

In addition to the pen modes, which can be used for text, text can also be drawn in 
eight special text-only modes (four modes and their opposites). The uses for the 
different text modes are shown in Table l6-3. The opposite modes (notForeCopy, 
notForeOR, notForeXOR, and notForeBic) work the same way as the original 
modes, except that the foreground pixels are turned to background pixels and the 
background pixels are turned to foreground pixels before the operation is 
performed. For more detail on how to use the modes, see the section 
“SetTextMode” in this chapter. 

Table 16-3 
Text modes 


Mode 


Description 


modeForeCopy, notForeCOPY 
modeForeOR, notForeOR 
modeForeXOR, notForeXOR 
modeForeBIC, notForeBIC 


Copies only the foreground pixels into the destination— 
background pixels are not altered 

ORs only the foreground pixels into the destination— 
background pixels are not altered 

XORs only the foreground pixels into the destination— 
background pixels are not altered 

BICs only the foreground pixels into the destination; that is, 
inverts the source pixels and AMDs them with the 
destination—background pixels are not altered 


If you need to know more about how fonts are drawn and constructed (if, for 
example, you want to write a font-editing application), see the section “Fonts and 
Text in QuickDraw H” in this chapter. 
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Drawing in coior 

The video display hardware of the Apple IIGS includes advanced color capabilities. 
Although tool calls make it unneccessary for you to manipulate the hardware directly, 
knowledge of a few background concepts will help you understand the way 
QuickDraw II manipulates the colors on the screen. 

The Apple IIGS offers two Super-Hi-Res graphics modes. Both modes have 200 scan 
lines, but the scan lines differ in horizontal resolution—one mode has 320 pixels (the 
color of each specified by four bits), and the other has 640 pixels (the color of each 
specified by two bits). In changing from 320 mode to 640 mode, the horizontal 
resolution is doubled at the expense of dividing the color resolution by 4. 

Both modes use a chunky pixel organization (in which the bits for a given pixel are 
contained in adjacent bits within one byte), as opposed to bit planes (in which 
adjacent bits in memory affect adjacent pixels on the screen). Therefore, the four 
bits of a pixel in 320 mode are in the same memory locations as the four bits of a pair 
of adjacent two-bit pixels in 640 mode. 

Colors on the Apple IIGS are determined from master color values, which are 
mathematical combinations of the primary red, blue, and green hues available on a 
color monitor. A master color value is a two-byte number, formatted as shown in 
Figure 16-19. 
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Figure 16-19 

Master color value 

A three-digit hexadecimal number can describe each master color, with one digit 
($0-$F) for each primary color. Thus, a master color value of $000 denotes black, 
$FFF is white, $00F is the brightest possible blue, $080 is a medium-dark green, and 
so on. Because each primary color has 16 possible values, 4,096 colors are possible. 

At any one time, the Apple IIGS uses only a small subset of all possible colors. An 
application does so by constructing one or more color tables, short lists of the 
available colors for any one pixel. 
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Color tables and palettes 

Pixels contain only two or four bits, and it takes 12 bits to specify a master color 
value. Thus, applications cannot use master color values to directly specify pixel 
colors. Instead, the pixel value is a two- or four-bit offset into a color table. 

A color table is a table of 16 two-byte entries. Each entry in the table is a master color 
value; any of the 4,096 possible color values may appear in any position in the color 
table. The colors available to the application, as specified in its color tables, 
constitute its palette* 

Pixels in 320 mode are represented in memory by four-bit integers. For each pixel, 
that four-bit value is used as an a offset into a color table. With four bits, there are 16 
possible pixel values, so the available colors for each pixel in 320 mode equals 
16—the entire color table—as shown in Figure 16-20. 
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Figure 16-20 

Accessing the color table In 320 mode 
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Pixels in 640 mode are represented in memory by two-bit integers. With two bits, 
there are only four possible pixel values to offset into the color table. To avoid 
limiting 640 mode to only four colors, however, each four adjacent pixels in 640 
mode use four different parts of the same color table; a color table, then, consists of 
four minipalettes, which needn’t have the same sets of master colors. Therefore, 
although each individual pixel in 640 mode can have one of only four colors, groups 
of four pixels can have a total of 16 colors from which to choose, as shown in 
Figure 16-21. 


Pixel 3 



Accessing the color table In 640 mode 


Offset into 
minipalette; 
maximum 
value is 3(11) 


How to use this ability to create a large variety of colors is described in the section 
“Dithered Colors in 640 Mode” in this chapter. 
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Scan line control bytes 

An application may constnict as many as 16 different color tables to choose from. 
Each of the 200 scan lines in Super Hi-Res graphics can use any one of the l6 tables. 
For each scan line, a scan line control byte (SCB) decides which color table is 
active, as shown in Figure 16-22. 


IH 


scbColorMode 
640 mode = 1 
320 mode = 0 


scblnterrupt 

Interrupt generated when scan line refreshed = 1 
No Interrupt generated when scan line refreshed = 0 

scbFHI - 
Fill mode on = 1 
Fill mode off = 0 


scbReserved 

Reserved for future use; set to 0 


cdorTable 

Color table number: 1 of 16 


Figure 16-22 

Scan line control byte 


The SCB also controls screen display mode 020 or 640), interrupt mode, and fill 
mode. 


Interrupt mode: Interrupts can be used to synchronize drawing with vertical 
blanking so pixels are not changed as they are being drawn (a pixel is drawn once 
every l/60 of a second). Interrupts can also be used to change the color table before 
a screen is completely drawn. This allows a program to show more than 256 colors 
on the screen at once but costs the overhead of servicing the interrupt. 

Fill mode: When fill mode is active, pixel values of 0 can be used to fill areas of 
color in 320 mode. 


❖ Note: Fill mode works only in 320 mode. 

A pixel with a numeric value of 0 serves as a placeholder indicating that the pixel 
should be displayed as the same color last displayed, as shown in Figure 16-23. 


Scan-line values 
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Black White Black 


Figure 16-23 
Fill mode example 
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standard color palette in 320 mode 

The standard palette (the default color table) for 320 mode is shown in Table l6-4. 

Table 16-4 

Standard palette in 320 mode 

Offset Color Value Offset Color Value 


0 

Black 

000 

8 

Beige 

FA9 

1 

Dark gray 

777 

9 

Yellow 

FFO 

2 

Brown 

841 

10 

Green 

OEO 

3 

Purple 

72C 

11 

Light blue 

4DF 

4 

Blue 

OOF 

12 

Lilac 

DAF 

5 

Dark green 

080 

13 

Periwinkle blue 

78F 

6 

Orange 

F70 

14 

Light gray 

CCC 

7 

Red 

DOO 

15 

White 

FFF 


Note: "Offset” means position in the color table and “Value” means master color value, the 
hexadecimal value controlling the fundamental red-green-blue intensities. 


Dithered colors in 640 mode 

Only four colors are available for each pixel in 640 mode. But when small pixels of 
different colors are next to each other on the screen, their colors blend. For 
example, a black pixel next to a white pixel appears to the eye as a larger gray pixel 
By cleverly choosing the entries in the color table, we can make more colors appear 
on the screen. This process is called dithering. 

At the same time, to preserve the maximum resolution for displaying text, both black 
and white must be available for each pixel. This leaves only two remaining colors per 
pixel to choose from, which seems like a severe restriction. But with dithering, you 
can have 640-mode resolution for text and still display 16 or more colors if you are 
willing to resort to a few simple tricks. 

Consider the following byte with four pixels in it: 


Bit value 
Pixel number 


Each pixel has the value 1, which is an index into the second place in each of the 
color table’s minipalettes (see Figure 16-21). So pixel I’s color is determined by 
entry 1 in minipalette 1, pbcel 2’s color is determined by entry 1 in minipalette 2, and 
so on. 


oh 

oj 1 

oh 

0 I 1 

1 

2 

3 

4 
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If we use the standard 640-mode color table (shown in Table l6-5), pixels 1 and 3 will 
appear blue ($0010 and pixels 2 and 4 will appear red ($EX)0). The eye will average 
these colors and see violet. 


Table 16-5 

Standard palette In 640 mode 


Offset 

Color 

Value 

Mlnipolette 

offset 

Offset 

Color 

Value 

Minipalette 

offset 

0 

Black 

000 

0 

8 

Black 

000 

0 

1 

Blue 

OOF 

1 

9 

Blue 

OOF 

1 

2 

Yellow 

FFO 

2 

10 

Yellow 

FFO 

2 

3 

White 

FFF 

3 

11 

White 

FFF 

3 

4 

Black 

000 

0 

12 

Black 

000 

0 

5 

Red 

DOO 

1 

13 

Red 

DOO 

1 

6 

Green 

OEO 

2 

14 

Green 

OEO 

2 

7 

White 

FFF 

3 

15 

White 

FFF 

3 


Note: The entries in the minipalettes for the standard 640-mode color table are set up so 
black and white appear in the same positions in each palette. This provides pure black and 
white at full 640 resolution, allowing crisper text display. 


There are 16 different combinations of values a pair of pixels can assume in 640 
mode, meaning that you can obtain l6 colors by dithering. To implement it, just 
make sure that the pattern you use for drawing or filling consists of a repeating array 
of four-bit (two-pixel) values. 


16-36 Chapter 16: QuickDraw I! 




Cursors 


A cursor is a small image that appears on the screen and is controlled by a mouse. 
(The cursor appears only on the screen, never in an ofF-screen pixel image.) The 
cursor record contains the height and width of the cursor, the cursor image of the 
cursor, the mask controlling the appearance of the cursor, and a hot spot defining 
where the image of the cursor will be placed by the mouse, as shown in Figure 16-24. 


Offset Field 



Word— INTEGER; total number of horizontal slices In cursor 

Word— INTEGER; number of words wide In single horizontal slice of cursor 

X Bytes— Array of words; cursor image (last word In each slice must be 0) 

X Bytes— Array of words; cursor mask (last word In each slice must be 0) 

Word— INTEGER; Y coordinate of hot spot 
Word— INTEGER; X coordinate of hot spot 


Figure 16-24 

Cursor record 

❖ Note: Because of its variable size, the cursor record is not provided in the APW 
interface file. 

The cursor appears on the screen as the size defined by the cursorHeight and 
cursorWidth fields in the cursor record. The appearance of each pixel is determined 
by the corresponding bits in the data mask and by the pixel under the cursor (that is, 
by the pixel already on the screen in the same position as this bit of the cursor). The 
image on the screen is obtained by ORing the mask with the destination and XORing 
that result with the cursor image. 

The hot spot aligns a pixel in the cursor image with the mouse location. Thus, a hot 
spot of (0,0) is at the top left of the image, and a hot spot of (8,8) would be in the 
center of a cursor defined as 16 pixels wide and 16 pixels high. 


Drawing to the screen and elsewhere 


16-37 

















The arrow cursor in 320 mode is defined as shown in the following assembly-language 
fragment: 


dc 

i* 

11,4* 

; Eleven 

slices by 

dc 

h» 

0000000000000000* 

; Cursor 

image 

dc 

h» 

OfOOOOOOOOOOOOOO’ 



dc 

h* 

OFFOOOOOOOOOOOOO* 



dc 

h* 

OFFFOOOOOOOOOOOO* 



dc 

h' 

OFFFFOOOOOOOOOOO* 



dc 

h* 

OFFFFFOOOOOOOOOO* 



dc 

h* 

OFFFFFFOOOOOOOOO * 



dc 

h* 

offfffffoooooooo* 



dc 

h* 

OFFOFFOOOOOOOOOO* 



dc 

h» 

OOOOOFFOOOOOOOOO* 



dc 

h* 

0000000000000000* 



dc 

h' 

FFOOOOOOOOOOOOOO* 

; Mask image 

dc 

h' 

FfFOOOOOOOOOOOOO* 



dc 

h* 

FFFFOOOOOOOOOOOO * 



dc 

h' 

FFFFFOOOOOOOOOOO* 



dc 

h* 

FFFFFFOOOOOOOOOO* 



dc 

h* 

FFFFFFFOOOOOOOOO* 



dc 

h* 

FFFFFFFFOOOOOOOO* 



dc 

h* 

FFFFFFFFFOOOOOOO* 



dc 

h* 

FFFFFFFFOOOOOOOO* 



dc 

h* 

FFFOFFFFOOOOOOOO* 



dc 

h* 

OOOOOFFFOOOOOOOO * 



dc 

i- 

1,1’ 

; Hot spot 


words 
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Using QuickDraw II 

This section discusses how the QuickDraw II routines fit into the general flow of an 
application and gives you an idea of which routines you'll need to use under normal 
circumstances. Each routine is described in detail later in this chapter. 

QuickDraw n depends on the presence of the tool sets shown in Table l6-6 and 
requires that at least the indicated version of the tool set be present. 


Table 16-6 

QuickDraw II—other too! sets required 


Tool set 
number 

Tool set 
name 

Minimum version 
needed 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 


The first QuickDraw II call your application must make is QDStartUp. Conversely, 
when you quit your application, you must make the QDShutDown call. 

All graphic operations are performed in GrafPorts. Before a GrafPort can be used, it 
must be opened with the OpenPort routine. Normally, you don't call OpenPort 
yourself—^in most cases, your application will draw into a window you've aeated with 
Window Manager routines, and these routines call OpenPort to create the window's 
GrafPort. Similarly, a GrafPort’s regions can be disposed of by the ClosePort 
routine. When you call the Window Manager to close or dispose of a window, it calls 
these routines for you. 

In an application that uses multiple windows, each is a separate GrafPort If your 
application draws into more than one GrafPort, you can call SetPort to set the 
GrafPort you want to draw in. At times, you may need to preserve the current 
GrafPort; you can do this by calling GetPort to save the current port, SetPort to set 
the port you want to draw in, and then SetPort again when you need to restore the 
previous port. 

Some toolbox routines return or expect points that are expressed in a common, 
global coordinate system; others use local coordinates. For example, when the 
Event Manager reports an event, it gives the mouse location in global coordinates, 
but your application may need to know where the mouse location is in the window's 
local coordinates. The GlobalToLocal routine lets you convert global coordinates to 
local coordinates, and the LocalToGlobal routine lets you do the reverse. 

The SetOrigin routine will adjust a GrafPort's local coordinate system. If your 
application performs scrolling, you'll use ScrollRect to shift the pixels of the image 
and then use SetOrigin to readjust the coordinate system after the shift. 
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You can redefine a GraflPort's clipping region with the SetClip or ClipRect routine. 
Just as GetPort and SetPort preserve the current GrafPort, GetClip and SetClip are 
useful for saving the GrafPort’s clipping region while you temporarily perform other 
clipping functions. This is useful, for example, when you want to reset the clipping 
region to redraw the newly displayed portion of a document that’s been scrolled. 

The lineTo routine draws a line from the current pen location to a given point, and 
the Line routine draws a line as an offset from the current position. You can set the 
pen location with the MoveTo or Move routine; you can set other pen characteristics 
with SetPenSize, SetPenMode, and SetPenPat. 

In addition to drawing text and lines, you can use QuickDraw II to draw a variety of 
shapes. Most of them are defined by a rectangle that encloses the shape. The 
following require you to call a series of routines to define them: 

■ To define a region, call the NewRgn routine to allocate space for it, then call 
OpenRgn, and then specify the outline of the region by calling routines that draw 
lines and shapes. End the region definition by calling CloseRgn. When you’re 
completely done with the region, call DisposeRgn to release the memory the 
region occupies. 

■ To define a polygon, call the OpenPoly routine and then form the polygon by 
calling procedures that draw lines. Call ClosePoly when you’re finished defining 
the polygon; call KillPoly when you’re completely done with it. 

You can perform the following graphic operations on rectangles, rounded-corner 
rectangles, ovals, arcs and wedges, regions, and polygons: framing, painting, 
erasing, inverting, and filling. These operations are described in the section “Basic 
Drawing Functions” in this chapter. 

You’ll use points, rectangles, and regions not only when drawing with QuickDraw II 
but also when using other parts of the toolbox. At times, you may find it useful to 
perform calculations on these entities. You can, for example, add and subtract 
points and perform a number of calculations on rectangles and regions, such as 
offsetting them, rescaling them, calculating their union or intersection, and so on. 

❖ Note: When performing a calculation on entities in different GrafPorts, you 
need to adjust to a common coordinate system first by calling LocalToGlobal to 
convert to global coordinates. 


Warning 

QuickDraw II doesn't forgive certain kinds of programming errors. Results will be 
unpredictable if you make any QuickDraw II calls before Initializing QuickDraw IL 
pass any bad handles to QuickDraw IL or make any QuickDraw calls with a bad 
port. Even an error code probably won't be returned If one of these kinds of 
errors is made, and your program may never get control again after one of these 
errors. Your application may not fail immediately; it may work for a while and 
then later fall for no apparent reason. You must be certain these types of errors 
can't occur In your program. 
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Fonts and text in QuickDraw li 

This section contains a detailed description of the handling of fonts and text in 
QuickDraw II, including the definition of an Apple IIGS font. 

❖ Note: Most application writers, most of the time, will not need any more 
information than is included in the previous sections about text handling in 
QuickDraw II. But if you are designing a font, writing a font editor, or using 
unusual fonts or an usually large variety of fonts, you’ll need the information 
presented in this section. 

❖ Macintosh programmers: The treatment of text drawing and text measurement 
on the Apple IIGS is similar to their treatment on the Macintosh. The IIGS font 
definition is similar to that of the Macintosh, and a simple conversion algorithm 
allows the IIGS to use any font developed for the Macintosh. Most Macintosh 
QuickDraw text calls are duplicated precisely in QuickDraw H. Any differences 
are due to one or more of the following: 

■ Some information has been added to the beginning of the font definition. 

■ Because Macintosh-like resources do not exist, the IIGS Font Manager performs 
differently from the Macintosh Font Manager. 

■ Some bounding box calls (TextBounds and its siblings) missing from 
Macintosh QuickDraw have been added. 

■ Some calls—^DrawCString, CStringWidth, and the like—have been added to 
handle the C string data type (a sequence of characters terminated by a 0 byte). 

■ The Font Manager is not closely integrated with QuickDraw II. (The interaction 
between QuickDraw II and the Font Manager is quite different), 

■ QuickDraw II does not scale text. However, the Font Manager can scale fonts as 
required. 


Font definition 

An Apple IIGS font consists of a variable-length header, followed by a Macintosh font 
record (this embedded Macintosh font is referred to as the MF part of the IIGS font). 
The header is of variable length to allow extra information to be added in the future. 

The MF part of a IIGS font is exactly like a Macintosh font, except for one thing—the 
high-order and low-order bytes of integers. The Macintosh’s 68000 microprocessor 
stores integers with the high-order byte first (that is, high-order byte at lower 
memory location); the IIGS’s 65816 microprocessor stores them with low-order byte 
first. In converting a Macintosh font to a IIGS font, the high-order and low-order 
bytes of each integer are swapped. This does not apply to the font strike (called 
bitimage in the font definition), which can be used as is. 

Apple IIGS font definition 

The IIGS font record is shown in Figure 16-25. 
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Offset 

$0 

1 

2 

3 

4 

5 

6 

7 

8 
9 

OA 

OB 

oc 


Field 


— 

offseToMF 

— 

— 

family 

— 

— 

style 

— 

— 

size 

— 

— 

verson 

— 

— 

fbrExtent 

— 


— 

fontType 

— 

— 

fIrstChar 

— 

— 

lasfChar 

— 

— 

widMax 

— 

— 

kemMax 

— 

— 

nDescent 

— 

— 

fRectWidth 

— 

— 

fRectHeight 

— 

— 

owTLoc 

— 

— 

ascent 

— 

— 

descent 

— 

— 

leading 

— 

— 

rowWords 

— 

1 bitfmage 1 

locTable \ 


j owTable j 

I I 


Word—INTEGER; offset in words to Macintosh font part 
Word—INTEGER; font family number 
Word—INTEGER; style font was designed with 
Word-INTEGER; point size 
Word—INTEGER; version number of font definition 
Word-INTEGER; font bounds rectangle extent 
X Byte$— Additional fields, if any 
Word-INTEGER; font type—ignored on Apple ligs 
Word-INTEGER; ASCII code of first defined character 
Word-INTEGER; ASCII code of last defined character 
Word-INTEGER; maximum character width 
Word-INTEGER; maximum leftward kern 
Word-INTEGER; negative of descent 
Word-INTEGER; width of font rectangle 
Word-INTEGER; height of font rectangle (font height) 
Word-INTEGER; offset in words to offset/width table 
Word-INTEGER; font ascent 
Word-INTEGER; font descent 
Word-INTEGER; leading 
Word-INTEGER; width of font strike in words 

X Bytes— Array (1 ...rowWords, 1 ...fRectHeight) of word; font strike 

X Bytes— Array (firstChar...lastChar + 2) of INTEGER; location table 

X Bytes— Array (flrstChar...lastChar + 2) of INTEGER; offset/width table 


Figure 16-25 

Font definition 
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Apple lIGS font header fields 

Some information about the font is contained in the header. Because fonts designed 
at a later time may include additional information that could be utilized by later 
versions of QuickDraw II, the header is of variable length. For upward and downward 
compatibility of QuickDraw II and IIGS fonts, the following two fields are particularly 
useful: 

offseToMF: Offset, in words, from this field to the Macintosh font CMF) part 
included in the IIGS font (specifically, to the fontType field). The header is therefore 
2 X offieToMFhyt^s long. In the version of QuickDraw II current at the time of this 
manual's publication, offseToMF = 6; thus, the header is 12 bytes. Future fonts may 
have longer headers that contain font information that can be utilized by future 
versions of QuickDraw II. To ensure that these improved fonts can be used by older 
versions of QuickDraw II, the offseToMF field provides a reliable jump over this 
extra font information to the start of the Macintosh part of the font. An older 
QuickDraw n will not be able to make use of new header fields added since it was 
implemented, but at least it will be able to find the information it can use. 

version: Version number of the font definition under which the font was designed. 
By checking this field, later versions of QuickDraw II can avoid trying to find and use 
information not included in an older font. (Presumably a newer QuickDraw II, 
alerted by the version number to the lack of such information, would use some 
default or calculated values.) The font definition described in this manual is 1.1 
($ 0101 ). 

Examples of extra information that may be included in later fonts and used by later 
versions of QuickDraw II include thickness of underline, slope of italicized letters, 
smearing extent of boldface, and the like (on the Macintosh, these are determined 
by the Font Manager). 

The other header fields are 

family: Integer identifying the font, regardless of size or style. This can be thought 
of as corresponding to the font's name—Courier or Geneva, for example. 

style: Style in which the font was designed. For example, application writers and 
graphic designers may design italic or bold fonts for reasons of aesthetics or time 
performance. When QuickDraw II is asked to apply a certain style when drawing a 
character or string, it first checks this field. If the field indicates that the requested 
style is already part of the font, the drawing call will not apply the styling algorithm. 
This would, for example, prevent a preitalicized font from being reitalicized. 

size: Relative measure of the size of fonts. The measure is analogous to the 
Macintosh point size; however, the actual font size is different from the true point size 
in a typographic sense. 

fbrExtent: Maximum horizontal distance, in pixels, from the character origin to 
the far edge of any foreground or background pi^el of any character in the font. (See 
the section “Font Bounds Rectangle” in this chapter for a more precise defim’tion.) 
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Macintosh font part of an Apple 116$ font 

A Macintosh font, or in this case the Macintosh font part of a IIGS font, consists of 

four sections; 

1. A fixed-length record containing general information, such as font height and 
maximum character width. 

2. The font strike (named bitimage in the font record definition), which is a pixel 
image containing the image of every character defined in the font, strung one after 
another. The pixel image is in a one-bit-per-pixel form. Its width, measured in 
words, is given by the rowWords field of the font record; its height, measured in 
pixels, is given by fRectHeight 

3. The location table (JocTable^, an array of integers that indicates for each defined 
character where its image in the font strike begins. 

4. The offset/width table (jowTabl^, an array of integers. For each character, the 
low-order byte of its entry in the offset/width table (the character offset) indicates 
how the character image to be drawn should be positioned with respect to the 
current pen location; the high-order byte indicates how far the pen should be 
advanced after the character is drawn (^character width). 

This table is also used to identify characters not defined in a font. An owTable 
value of -1 ($FFFF) marks a missing character, which must be handled specially 
by the text calls. 

A detailed description of the meanings and uses of these various fields and arrays is 

given in the sections that follow. 


Characters 

A character image is a rectangular array of bits, representing pixels. The on, or 1, 
bits are called the character foreground pixels. 

The number of columns in a character image is called the character Image width, 
or just the image width. Note that a character can have an image width of 0. For 
example, the space has a 0 image width; its character image consists of no pixels at 
all. 

The character rectangle is a rectangle that encloses the character image. Its width 
is the image width of the character, which may vary from character to character in a 
font; its height is the character height, which is the same for all characters in a font. 


16-44 Chapter 16: QuickDraw II 



Each character has a number associated with it. This number, called the character 
width and found in the offset/width table, is the number of pixels the pen position is 
to be advanced after the character is drawn. This is different from the image width, 
and the distinction between the two is important. For example, the space character 
has 0 image width but does have some positive character width, which determines the 
size of the space. Some characters have a nonzero image width but a 0 character 
width; an example of this is an umlaut, which is meant to be typed over a vowel. The 
umlaut is drawn first, and then the vowel is drawn with the same pen location. 
Characters with 0 character width are called dead characters. 

Also associated with every character in a font are its base line and its character 
origin. The base line is a horizontal line that separates the image into two sets of 
rows, one set above and one below. (Remember that in QuickDraw II, as in 
QuickDraw, horizontal and vertical lines fall between pixels rather than running 
through them.) The position of the base line depends on the font’s ascent and 
descent fields; it is chosen so there are ascent rows above it and descent rows below. 
The base line will be in the same horizontal position for every character in the font 
Any foreground pixels of a character image that lie below the base line are 
collectively called the character’s descender. Most characters don’t have a 
descender, but in an average font, characters like q and y do. 

The ascent line is the horizontal line just above the top row of a character; the 
descent line is the line just below the bottom row. These will be the same for every 
character in the font. 

The character origin of a character is a point on the base line used to position the 
character for drawing. This point may be between pixels of the character image, to 
the right of them, or to the left. (Here, note that points lie between pixels, not on 
them.) Its location relative to the character image can be calculated by the character 
offset in the offset/width table, as detailed in later sections of this chapter. When the 
character is drawn, it is placed in the destination pixel image so that its character 
origin coincides with the current pen location. 

For many letters, the character origin is located on the left edge of the character 
image so that, when the character is drawn, its leftmost foreground pixels fall just to 
the right of the pen. Sometimes the character origin is between pixels of the 
character image (or, rarely, entirely to the right of the image), ^^en such a 
character is drawn, some of its pixels will fall to the left of the pen position. This is 
called kerning to the left. In such a case, the distance, in pixels, from the character 
origin to the left edge of the character is called the character’s leftward kem. 

When character-image pixels fall to the right of the new pen position after the 
character is drawn, the character is said to kem to the right. The kemMax field in a 
font is concerned only with kerning to the left. Kerning in either direction can cause 
letters to overlap each other. See Figures 16-26 and 16-27. 
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Character 

origin 



Ascent line 


Character 

rectangle 

Base line 


Font 

height 


Next character origin 
Descent line 


Image width 


Figure 16-26 

Character with no kerning 


Character width 



Image width 


Figure 16-27 

Character kerning left 
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Fonts 


Font rectangle 

Imagine all the defined characters of a font drawn so their character origins 
coincide. The result would be a black mess of foreground pixels. The smallest 
rectangle completely enclosing this mess is called the font rectangle (see 
Figure 16-28). 


kernMox 



Figure 16-28 

Font rectangle (simulated) 


The fields of the font record that measure aspects of the font rectangle are described 
in the following list: 

kernMax: Distance, in pixels, from the font rectangle's common character origin 
to the left edge of the font rectangle. If any character in the font actually kerns to the 
left, kemMax is represented as a negative number. If the character origin lies on the 
left edge of the font rectangle, kemMax is 0. 

Most fonts fall into these two categories. However, in some fonts, the left edge of the 
font rectangle is one or more pixels to the right of the character origin. In such a 
case, kemMax is assigned a positive value, even though this bends the terminology 
a bit; for example, people do not usually say of a character that leaves two columns of 
blank pixels between the pen position and its image that it kerns to the left 2 pixels, or 
-2 pixels, or anything at all. 

fRectWidth: Width, in pbcels, of the font rectangle. Note that this may be more 
than the maximum character image width because the font rectangle's left and right 
extremes may come from different characters. 

fRectHeight: Height, in pixels, of the font rectangle. 
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ascent: Number of pbcel rows above the common base line in the font rectangle. 

descent: Number of pixel rows below the base line in the font rectangle. Note that 
fRectHeight = ascent + descent. 

nDescent: Negative of descent. 

❖ Note; For typical fonts—those in which the font rectangle at least touches its 
character origin —ascent and descent will be non-negative, and kemMax and 
nDescent will be nonpositive. However, fonts can be designed without these 
restrictions. 

fontType: QuickDraw n ignores this field. 

firstChar: ASCII code of the first defined character in the font. 

lastChar: ASCII code of the last defined character of the font. 

widMax: Maximum character width (pen displacement) of any character in the font, 
measured in pfacels. 

owTLoc: Offset, in words, from this field to the font offset/width table (.owTable). 

By adding 2 x owTloc to the memory address of this field, you get a pointer to the 
owTable. There is no corresponding field for the location table in the font record; 
to get a pointer to the locTable, you must subtract 2 x QastChar- firstChar + 3) from 
the owTable pointet. 

leading: Recommended number of blank pixel rows between the descent row of one 
line of text and the ascent row of the next Applications may use this or not, as they 
please. 

rowWbrds: Width of the font strike, in words. This is discussed further in the next 
section, “Font Strike.” 

Font strike 

The font strike (called bttimage in the font definition) is a one-bit-per-pixel pixel 
image consisting of the character images of every defined character in the font, 
placed sequentially in order of increasing ASCII code from firstChar xo lastChar+1. 
The character images in the font strike abut each other, no blank columns are left 
between them; see Figure 16-29. 



Figure 16-29 
Part of a font strike 
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Because all the characters of a font have the same height, the font strike is just one 
long pixel image with no jumps or undefined stretches and with a height of 
JRectHeight. The strike is padded on the right, if necessary, with enough extra pixels 
on each row to make the row width a multiple of 16—that is, to make each row an 
integral number of words. This width, measured in words, is found in the ivwWords 
field of the font record. 

Defined versus undefined characters 

Not every possible ASCII code must have a character image in the font strike. The 
font may leave some characters undefined; these are called missing characters. 
Every character with a code less than firstCharot greater than lastChar+ 1 is 
undefined. There may be other undefined characters as well. The ofFset/width table 
CowTable^ has an entry for every code from firstCharlo lastChar+ 2, inclusive. If a 
character’s entry in the offset/width table is -1 ($FFFF), the character is undefined or 
missing. 

Character code lastChar+ 1 is a special case. Immediately following lastChar in the 
font strike is a character Ocnown as the missing symbol) that is to be used in place of 
any missing character. This character must be present in the font strike. It has 
entries in the locTable and the owTable, and its entry in the owTable must not be -1. 
For all purposes, the missing symbol is a defined character with ASCII code 
lastChar + 1. In many fonts, the missing symbol is a hollow reaangle; in the current 
system font, it is a white-on-black question mark. 

Whenever the QuickDraw II text-handling routines encounter a missing character— 
less than flrstChar, greater than lastChar-^ 1, or having an owTable enxiy of-1—the 
routines immediately substitute the missing symbol for the character, using the 
missing symbol’s character image, locTable entry, and owTable entry wherever 
needed. 

Location table 

The location table QocTabli) is an array of integers with an entry for each character 
code from firstCharlo lastChar + 2. It is used to find character images in the font 
strike. For each defined character, the locTable entry gives the distance, in pixels, 
from the beginning of the font strike to the beginning of the character’s image in the 
font strike (“beginning,” here, means left edge). This indicates where the character 
image starts. To see where it ends, take the next locTable entry (the beginning of the 
next character image) and subtract 1. Because the character images abut each other, 
this will give you the precise limits of the character image. The image width of a 
defined character with code 6* is locTablelC-^ 1] - locTable[C\, This may be 0. 
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For this scheme to work, two conditions must hold: 

1. The locTable entry for an undefined character must be the same as the entry for 
the next defined character. This prevents undefined characters, which have no 
image in the strike, from interfering with the hunt for images of defined 
characters. 

Note that there always will be a next defined character because the missing 
symbol, which serves as a defined character, is tacked on at the end of the strike. 

2. To get the character image for the missing symbol, there has to be an entry in the 
locTable following the missing symbol entry. For this reason 
locTablellastChar-^ 2] is included and is set equal to the length of the font strike in 
pbcels, ignoring the padding that is added to the font strike to align it to word 
boundaries. 

Offset/width table 

The offset/width table iowTable) is an array of integers with an entry for each 
charaaer code from firstCharxo lastChar-^ 2. If a character’s entry is -1, the 
character, is undefined (missing). Otherwise the entry’s low-order and high-order 
bytes are the character width and character offset, resi>ectively. Both are interpreted 
as numbers in the range 0-254 (255 is ruled out to avoid the case where both bytes are 
255, giving an entry of -1, which would mark a missing charaaer). 

The character offset is used to calculate the position of character origin relative to the 
image in the following way: The offset is added to the font’s kemMax, The result is 
the (horizontal) distance, in pixels, from the character origin to the left edge of the 
image. If the result is negative, then the origin is to the right of the image’s left edge 
(the character kerns leftward). If the result is positive, the origin is to the left of the 
image’s left edge. (A result of 0 means that the character origin sits on the left edge of 
the image). Because we already know that the charaaer origin must lie on the base 
line (whose position is determined from ascent and descent), this precisely locates 
the origin. 
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If you draw the font rectangle and look at a particular character’s character rectangle 
within it, the character offset is seen to be the offset, in pixels, between the left edge 
of the font rectangle and the left edge of the character rectangle. See Figure 16-30. 



Character 

offset 


Figure 16-30 

Character rectangle in font rectangle 

The low-order byte of the owTable entry gives the character width, which is the 
distance, in pixels, the pen should be advanced to the right after the character is 
drawn. In applications, this distance can be affected by a number of calls, 
particularly SetCharExtra and SetSpaceExtra. There is, however, a general rule in 
QuickDraw II: any character whose character width (taken unmodified from the 
owTabli) is 0 will not have that width changed by chExtra, spExtra, style 
modifications, nonproportionality, or any other effect. We assume that characters 
are given 0 width only for some very good reason. 


Warning 

Any modification, or any combination of modifications, that results In a character 
width of less than 0 or greater than 255 will wreak havoc with the drawing 
routines and is not allowed. This Includes chExtra, spExtra. and style 
modifications, among others. QuickDraw II does not check for this condition. 

That is up to you. 


The lastChar+ 2 entry of the owTable is set to -1. 
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Character backgrounds 

A character’s foreground consists of all the on pixels (1 bits) in its image. The off 
pixels (0 bits) are part of the background. In QuickDraw II, the background is extended 
on the left to include any pixels that are to the left of the image’s left edge but to the 
right of the character origin (and between the ascent and descent lines). On the right 
side, the background is extended to include any pixels (between ascent and descent) 
that are to the right of the image’s right edge but to the left of the character origin of the 
next character (that is, to the left of the new pen position). Any new pixels added in 
this way are also considered background pixels. In other words, the foreground of a 
character consists of all 1 bits in its character image. The background consists of all 0 
bits in the image plus all nonforeground pixels that are to the right of the character 
origin, to the left of the subsequent character origin (character origin + character 
width), above the descent line, and below the ascent line. In some cases, no extending 
is needed. If the character kerns to the left, no left extension is necessary; if it kerns to 
the right, no right extension is needed. 


This is a very natural definition of background. If you’re going to draw a green 
charaaer that doesn’t stretch entirely from the old pen position to the new and you 
have a red background, the red background will usually extend a little to the left 
and/or right of the character’s image. This is what people generally want for a 
background. But in addition to this, when characters do kern, the background 
extends as far left or right as the kerning, so the kerned part of the character doesn’t 
jut out past the character’s background. 

This brings us to the definition of the character bounds rectangle (Figure 16-31). 

It is the smallest rectangle enclosing all the foreground and background pixels of a 
character. It may be somewhat larger than the character rectangle, which encloses 
the image, because the bounds rectangle takes into account the character width (pen 
positions) as well as the image width. The width of a character’s bounds rectangle is 
called the character bounds widths QuickDraw II includes calls for measuring 
character bounds rectangles and corresponding routines for strings, C strings, and text. 


Character bounds width 



Ascent line 

Character bounds 
rectangle 

Character 

rectangle 


Base line 

Next character origin 
Descent line 


Figure 16-31 

Character bounds rectangle 
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Font bounds rectangle 

To get some new, useful measures for the width of a font, we define the font bounds 
rectangle. Imagine that, for all of a font’s characters, the characters’ bounds 
reaangles were drawn so all the character origins coincided. The resulting rectangle 
(more precisely, the rectangle that is the union of all these rectangles) is called the 
font bounds rectangle. This rectangle, illustrated in Figure 16-32, includes all 
pixels, foreground and background, of every character in the font. (Consequently, it 
may be bigger than the font rectangle, which is only guaranteed to include all the 
foreground pixels.) 

We define JbrWidth to be the width of the font bounds rectangle, JbrRightExtent to 
be the distance from the common character origin to the right edge of the font 
bounds rectangle, and JbrLeftExtent to be the distance from the origin to the left 
edge (all distances measured in pixels and as positive numbers). Finally, we define 
JbrExtent to be the maximum of JbrLeftExtent and JbrRightExtent. 


kemMox wldMox 



Figure 16-32 

Font bounds rectangle 

The JbrExtent value is the farthest possible hori 2 ontal distance from the pen location 
to the far edge of any pixel that can be altered by drawing any character in the font. 

In many ways, this is a more precise measure of the width of a font than widMax or 
JRectWtdth. 

It would seem from Figure 16-32 that JbrLeJtExtent and kemMox are the same, or 
rather that JbrLeftExtent = -kemMox. This is tme if, and only if, kemMox is 0 or 
negative; if kemMox is positive (that is, if every character image starts at least 1 pfacel 
to the right of the character origin) then JbrLeJtExtent is 0. This makes JbrLeJt^ent 
easy to calculate. It would also seem as if JbrRightExtent is the same as tvidMox, but 
if any character kerns to the right beyond the reach of widMox, JbrRightExtent will 
be bigger than widMox. 


Fonts and text in QuickDraw 


16-53 


















































<♦ Macintosh programmers; The JbrExtent field is needed for safe handling of the 
text buffer. It is not included in the Macintosh font definition. If you are 
converting a Macintosh font to the IIGS, JbrExtent can be calculated by using the 
CharBounds call on character codes 0-255 and doing some simple arithmetic 
(the CharBounds call itself doesn’t need a valid value for JbrExtent, so it can be 
called for the calculation). This has to be done only once for each font. 


Drawing and the text buffer 

whenever a character or string is to be drawn, it is first drawn into the text buffer, a 
one-bit-per-pixel pixel image reserved for the private use of the QuickDraw II text¬ 
drawing calls. For strings, only those characters that have a chance of making it into 
the destination pixel image are actually drawn; the others, both to the left and to the 
right, contribute only to the cumulative pen displacement. Thus, there is no reason 
for an application to try to dip characters out of long strings unless it has a very fast 
way of doing so. 

The text buffer is empty at the beginning of each drawing call. Successive characters 
of a string are drawn into it, with an internal text buffer pen incremented by the 
character width each time. Regardless of the ultimate text mode (jxMode in the 
GrafPorO, characters are drawn into the text buffer in OR mode. Thus, characters 
that kern into each other do not interfere destructively. (For this reason, with certain 
text modes, such as modeForeXor, the results you get if you put up a string one 
character at a time with DrawChar can be different from those you get if you put up 
the whole string with DrawString. In the case of DrawChar, overlapping characters 
may cancel out some pixels.) 

Once the character or string is safely in the text buffer, any requested style 
modifications (underlining, bolding, and the like) are applied to it. Then the text 
buffer is transferred to the destination. Individual bits are replaced with two or four 
bits, depending on the chunkiness of the destination; the bit patterns used are the 
Grafporf s fgColor for the 1 (foreground) bits and bgCoIor for the 0 (background) 
bits. During the transfer, the text image is clipped to the current clipping region. 
The surviving pixels are combined with the destination's pixels, according to 
whatever text mode is in use. If and when the result makes it to the screen, the bit 
patterns will be translated into colored pixels according to the current color map(s). 
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Controlling text display 

Various QuickDraw II calls afFea text display. Generally, the calls set some field of 
the current GrafPort that is used in the text-drawing process. Matching the calls that 
set the fields are corresponding calls that return the value of the fields. 

SetForeColor, GetForeColor, SetBackColor, GetBackColor, SetTextMode, and 
GetTextMode deal with the GrafPort fields JgColor, bgColor, and txMode, whose 
effects were described earlier. The other display control calls deal with character 
spacing, style modifications, boldfacing, underlining, and font flag options, as 
described in the following sections. 

Character spacing calls 

SetCharExtra, GetCharExtra, SetSpaceExtra, GetSpaceExtra: These calls set 
and/or get the chExtra and spExtra fields in the GrafPort; those fields can alter the 
character widths (pen displacement) when characters are drawn. Each is a fixed 
number with a one-word integer part and a one-word fractional part. 

The chExtra field was included because some fonts that look fine in 320 mode appear 
too closely spaced in 640 mode. Putting an extra pixel between letters seems to help 
in these cases. 

The chExtra value is added to the character width of each character, except a dead 
character, as it is drawn. The chExtra value is not added to dead characters, which 
have a character width of 0. 

Adding chExtra to a character width will give us character origin positions that have a 
fractional part. During any text-drawing call, QuickDraw II keeps track of this 
fractional part and, when drawing a character, rounds its character-origin position 
to the nearest integer (1/2—that is, $8000—^is rounded up). The fractional part is not 
remembered after the call has been completed. 

Commonly used to help in justifying text, spExtra works the same way as chExtra 
except that it is only applied to the space character. Note that here “space character” 
means ASCII $20 and nothing else. In particular, the nonbreaking space included in 
many fonts is unaffected by the spExtra field. The spExtra value is cumulative with 
chExtra. 

These values are set by the QuickDraw II routines SetCharExtra and SetSpaceExtra 
(and can be fetched by GetCharExtra and GetSpaceExtra). In theory, the application 
can set chExtra and spExtra to any fixed value, even a negative one. However, any 
values that cause a character to have a character width of less than 0 or greater than 
255 pixels will cause no end of trouble. 
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style modification calls 

SetTextFace, GetTextFace: These calls set and get the txFace field of the 
GrafPort, which determines the style to be applied to the text At the time of 
publication, the following bits were defined: 

Bit 0 Bold 

Bit 1 Italic—available only if QuickDraw n Auxiliary is loaded and started up 

Bit 2 Underline 

Bit 3 Outline—^available only if QuickDraw n Auxiliary is loaded and started up 

Bit 4 Shadow—^available only if QuickDraw 11 Auxiliary is loaded and started up 

These styles may affect the character width (pen displacemenO, image width, ascent, 
and descent associated with a character or string. For example, boldfacing spaces 
characters farther apart and makes the characters thicker. These changes are 
reflected in the results returned by the width routines (CharWidth, StringWidth, and 
so on), the bounds routines (CharBounds, StringBounds, and so on), and the 
GetFondnfo routine. 

Font flogs option calls 

SetFontFlags, GefFontFlags: The JbntFlags field of the GrafPort is set by 
SetFontFlags and fetched by GetFontFlags. At the time of publication, only the last 
three bits (bits 2-0) of ttiis word are defined; bits 15-3 are reserved and should be set 
to 0. 

Bit Of If bit 0 is set, the font is used as a nonproportional font; every character, 
except characters with character width 0, is given the same character width, namely 
widMax (the maximum character width field from the font definition). 

When nonproportioiulity is in effect, chExtra, spExtra, style modifications, and so 
forth, are applied to the character width after it has been set to uHdMax. 

Bit I: As of Version 2.0, if bit 1 is set and bit 0 is not, every character in the font is 
given the same character width, just as occurs with the nonproportionality setting. 

However, in this case, the width used is the character width of the font’s digit 0 (ASCII 
$30). 

This feature makes it easier to line up columns of figures. It makes all digits, spaces, 
periods, and the like, the same width. “Width,” here, means character width; that is, 
the pen displacement after the character is drawn. (The image width of the 
characters remains unchanged.) Of course, standard nonproportionality would also 
make everything line up, but in most fonts, uHdMax is a good deal more than the 
width of a digit, which causes numbers to end up spaced too far apart 

Because the width vised in numeric spacing is usually less than widMax, some 
characters—for instance, W’s and M’s—end up overlapping other characters. 
Consequently, numeric spacing is useful with the characters most commonly used 
with numbers—space, period, and so on—^but is not appropriate for general text. 
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If you want absolute control over the width of characters, you can use numeric 
spacing or the standard nonproportionality and then adjust it to your tastes using the 
SetCharExtra routine. 

When numeric spacing is in effect, chExtra, spExtra, style modifications, and the 
like, are applied to the character width after it has been set to the width of the digit 0. 

Bits 1 and 0 should not both be set to 1. 

Bit 2: Bit 2 controls how the foreground and background colors in the GrafPort are 
applied to text when it is drawn. If bit 2 is 0, the foreground and background colors 
are treated as pixel values (two- or four-bit numbers depending upon the GrafPort’s 
SCB), with all other bits in the word ignored. Each foreground pixel is given the 
value of the foreground color value, and each background pixel is given the value of 
the background color value. For example, in 640 mode with a foreground color word 
of 0110011001100110 and bit 2 set to 0, each pixel will have a value of 10. 

If bit 2 is set to 1, the foreground and background colors are treated as a word*s worth 
of pixel values. This feature is useful when you are trying to draw text in 640 mode 
using dithered colors. Each foreground pixel in a destination word is given the value 
of the corresponding pixel in the foreground color word. Each background pixel in a 
destination word is given the value of the corresponding pixel in the background 
color word. For example, in 640 mode with a foreground color word of 
0110011001100110 and bit 2 set to 1, odd-numbered pixels will have a value of 10 and 
even-numbered pixels will have a value of 01. 


Using the QuickDraw II font calls 

Text drawing calls 

DrawChar, DrawText, DrawStrlng, DrawCStiing: These calls are used when the 
specified character or string of characters is drawn, using all the current 
information—^font, style, mode, and so forth. The current pen position is used as 
the character origin of the first character. The pen is advanced by the sum of the 
character widths. Note that, although the text image is clipped to the current clip 
region, the pen is not clipped in any way, the new pen position can be outside the 
current GrafPort bounds. 


Warning 

Near the edges of Its drawing space (±16Kd:16K), QuickDraw II Is unreliable; this 
applies to text drawing as well as to any other kind. Calls that would draw 
outside the space can cause catastrophic results. 
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Text width calls 

CharWidth, TextWidth, StringWidth, CStringWldth: These calls return the total 
pen displacement that would result if the character or sequence of characters were to 
be drawn. Nothing is actually drawn, however. The width calls take into account 
current styles, chExtra, spExtra, font flags, and the like. But they do not take kerning 
(which is independent of pen displacement) into account; that’s a job for the text 
bounds calls. Note that the width calls only return a pen displacement, not a new pen 
location. They make no use of the current pen location, and they don’t change it. 

Text bounds calls 

CharBounds, TextBounds, StrIngBounds, CStrlngBounds: These calls return 
the smallest rectangle that would enclose all the foreground and background pixels of 
the character or string (or text block or C string) of characters if they were to be 
drawn, starting at the current pen location. The rectangle is given in the local 
coordinates of the current GrafPort. 

Unlike the text width calls, these calls take kerning, as well as pen movement, into 
account. The bounds rectangle extends to the left as far as the starting pen position 
or the leftmost kerning pixel (if any) of the text image, whichever is farflier to the left. 
Similarly, it extends as far right as the new pen position or the rightmost kerning 
pixel, whichever is farther to the right. But at the least, the bounds reaangle is 
reliable; any pixel that might be changed by a text-drawing call is inside the 
corresponding bounds rectangle. 

The rectangle extends up (from the current pen location) to the ascent line and down 
to the descent line. It is not clipped to any clipping region. It takes into account 
style modifications, chExtra, spExtra, and so forth. Note that the bounds rectangle is 
not actually drawn by these calls; its coordinates are simply returned to the 
application. 

Some strings (or text or C strings), or possibly even some characters, may have no 
foreground or background pixels. Such a character would have to have 0 image width 
and 0 character width—a space with no length. A string may have 0 length (no 
characters) or be composed entirely of the spaceless spaces just described. In these 
cases, the text bounds calls return a degenerate rectangle; that is, one whose right 
and left edges are the same (namely, the current pen location’s X coordinate). The 
upper and lower edges of the rectangle will be the ascent and descent lines (relative to 
the pen’s Y coordinate), as usual. 

Text buffer nrianagement calls 

SetBufDlms, ForceBufDims, SaveBufDims, RestoreBufDlms: These calls 
affect the size of the text buffer and the way it is used. 

❖ Note: If you are using the Font Manager, it takes care of all this text buffer 
management for you. 
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Important 

These calls affect the QuickDraw II clip buffer as well as the text buffer! 


When a string (or text block or C string) is to be drawn into a pixel image, it is first 
drawn into the text buffer. Characters of the string that fall far outside the 
destination’s left or right boundaries are not actually drawn into the text buffer; only 
their character widths are used—to determine where the string actually enters the 
destination (on the right) and/or what the final pen location should be (on the left). 

For the text-drawing calls to handle this safely and efficiently, QuickDraw II must have 
certain information about the largest pixel image sizes and character sizes it will have 
to deal with. For one thing, the text buffer must be at least as wide (in pixels) as the 
widest destination pixel image that may be used (actually, it must be a little wider to 
avoid disaster when drawing characters that fall partly in and partly out of the 
destination), and it has to be as high as the highest font For another thing, to decide 
if a pen location is so far outside the destination that a character drawn with that 
origin can’t possibly impinge on the destination, QuickDraw II needs to know the 
width of the widest possible character. “Widest,” here, includes not only image 
width and character width, but also any elongations due to chExtra, spExtra, style 
modifications, and so forth. Any pixel that can be touched by a character’s 
foreground or background must be considered. 

This is what JbrExtent was created for. It describes how far away from the current pen 
location any pixel that can be altered can be. But JbrExtent depends only on the 
font and does not take into account style modifications and the like. This is why we 
have two calls: SetBufDims, which provides generous defaults for any character 
elongations, and ForceBufDims, which puts things more under the application’s 
control. 

When QDStartUp is called, it creates a text buffer that is twice as high as the system 
font, wide enough to support the maxWidth parameter of QDStartUp, and capable 
of handling charaaers twice as wide as the system font characters (“wide” in the sense 
of JbrExtent), It also permits the use, with any font, of any chExtra ^ JbrExtent (of 
that font); SpExtra < JbrExtent; and it allocates up to 36 extra pixels per character to 
accomodate style modifications (bolding, for example, adds 1 pixel to a character, 
and italicizing a large font can stretch its horizontal extent significantly). If your 
application is going to deal only with fonts and text display parameters that fall within 
those limits, you can trust to the defaults and never call SetBufDims or 
ForceBufDims. 

The SetBufDims routine takes three parameters: 

maxWidth INTEGER 

maxFontHeight INTEGER 

maxFBRExtent INTEGER 
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The maxWidth value is the width in bytes (not pixels) of the largest pixel image the 
application will draw into (a value of 0 indicates screen width). It will override the 
value supplied to QDStartUp. The maxFontHeight value is the height, in pixels, of 
the tallest font the application will have to work with. The maxFBRExtent vzlue is the 
fbrExtent of the widest (that is, greatest JbrExtent) font the application will work with. 
The call resizes the clip buffer and the text buffer to accommodate these sizes. 

In addition, SetBufDims pads the text buffer to allow for (1) values of chExtra and 
spExtra < the JbrExtent of the font in use at any given time and (2) an extra 36 pixels 
of style modification added to the width of any character. 

SetBufDims's three parameters are used to size QuickDraw IPs internal buffers. When 
it's time to actually draw a string, and QuickDraw II must decide which characters 
might make it into the destination, it uses the fbrExtent of the current font (which 
may be way smaller than maxFBRExteni), the current values of spExtra, chExtra, 
txFace, and so on, and for a destination pixel image width, the width of the active 
portion of the current GrafPort's pixel image (its minRect, to be specific). 

Therefore, large values for SetBufDims's parameters may soak up some memory for 
the text buffer size but will not cost much in time lost drawing into the text buffer 
characters that will never make it into the destination. This also means that, once the 
text buffer is sized, the maxFBRExtent parameter can be forgotten. (This is not true 
for ForceBufDims.) 

ForceBufDims takes the same parameters as SetBufDims and performs the same 
functions; however, it does not pad the text buffer at all. Any extra pixels that might 
be added to a character bounds width due to chExtra, spExtra, style modifications, 
or whatever, should be added into the maxFBRExtent parameter by the application 
making the call. 

ForceBufDims, like SetBufDims, sizes the buffer(s) on the basis of its parameters, 
and when a string is actually drawn, only the width of the current GrafPort's pixel 
image is considered, not all of maxWidth But, unlike SetBufDims, ForceBufDims 
forces QuickDraw II to use the maxFBRExtent parameter to decide which characters 
are in and which out, rather than trying to calculate a current JbrExtent value. 
ForceBufDims is for those times when you're going to do something so unusual that 
QuickDraw II won't be able to anticipate your actions (such as using very large 
chExtra or spExtra values). Consequently, when ForceBufDims is called, its 
maxFBRExtent value must be remembered for subsequent drawing calls. In the 
SaveBufDims and RestoreBufDims, there is an asymmetry in the parameters handed 
back, depending on whether the text buffer was originally set (jnaxFBRExtent no 
longer needed) or forced (maxFBRExtent must be remembered). Precise 
calculations of maxFBRExtent for the ForceBufDims call are not necessary; upper 
limits will do. 
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You can of course call SetBufDims or ForceBufDims every time you change fonts or 
even every time you call SetCharExtra and SetTextFace. This is not recommended, 
however, because sizing (and clearing) buffers can be quite time-consuming. The 
routines should probably be called only once (if at all), with the maximum realistic 
values for each of the parameters, and never again. 

InflateTextBuffer takes two parameters: newWidth, a font width (that is, JbrExtent in 
pixels); and newHeight, a font height (in pixels). It then calculates whether the 
current dimensions of the text buffer are large enough to accommodate a font with 
that width and height and, if they are not, the routine enlarges the text buffer so that it 
can handle fonts of that size. The routine will never shrink the size of the text buffer. 
InflateTextBuffer always pads the value of newWidth to allow for style modifications 
and for reasonable values of chExtra and spExtra, 

❖ Note: If the current text buffer size was set by a SetBufDims call, then when 
InflateTextBuffer enlarges the text buffer, it makes an internal call to SetBufDims, 
so the new width is also considered a “set” value. However, if the text buffer 
currently has a “forced” width, as set by ForceBufDims, InflateTextBuffer will 
enlarge the buffer by first padding the newWidth value and then calling 
ForceBufDims with this padded value as the “forced” font width. 

SaveBufDims and RestoreBufDims are included for orderly context-switching 
between subprograms. SaveBufDims saves the state of the clip buffer and text buffer 
sizes in the form of an eight-byte record: 

maxWidth INTEGER 

textBu/Height INTEGER 

textBufferWords INTEGER 

fontWidth INTEGER 

The maxWidth value is the current value of the application-set maximum pixel image 
width in bytes. The textBu/Height value is the current text buffer height in pixels, and 
textBufferWords is the current width of the text buffer in words. The fontWidth value 
serves two purposes: if it is 0, it means the buffer was set up with a call to SetBufDims; 
if it is nonzero, the buffer was set up with a call to ForceBufDims, and the value of 
fontWidth is equal to the maxFBRExtent parameter used in that call. 

RestoreBufDims restores the buffer dimensions on the basis of the record it is given. 

Regardless of which call—QDStartUp, SetBufDims, ForceBufDims, or 
RestoreBufDims—^sizes or resizes the text buffer, the application is not responsible 
for clearing it The calls take care of clearing the text buffer automatically. Also note 
that SaveBufDims and RestoreBufDims do not save and restore the contents of the 
text buffer; they restore only the parameters related to its size. 
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Font information calls 

GetFontInfo, GetFontGlobals, GetFGSize, GetFontLore: These calls are 
included for gathering information on the current font. GetFontInfo returns 
information in the following font info record: 

ascent INTEGER 

descent INTEGER 

widMax INTEGER 

leading INTEGER 

These values have been modified, if necessary, to reflect style modifications 
currently in effect. 

GetFontGlobals returns a variable-length font globals record as follows: 

fgFontID INTEGER 

fgStyle INTEGER 

fgSize INTEGER 

fgVersion INTEGER 

fgWidMax INTEGER 

fgFbrExtent INTEGER 

(Additional fields may be present at the end of the record.) 

The fgWidMax value is taken from the embedded Macintosh font; all the others are 
from the Apple IIGS header. They are taken directly from the font and are not 
modified, regardless of any style modifications in effect. 

In the future, more information will probably be added to the font globals record. 
The GetFGSize routine exists to warn the application about the added information. 
The routine returns the length in bytes of the font globals record. Future versions of 
QuickDraw n may add extra information at the ends of their font globals records, but 
for compatibility, those versions will maintain the documented fields and ordering 
of earlier versions. 

GetFontLore returns the same information as GetFontGlobals in the same order. 
However, the application can use GetFontLore and specify the maximum number of 
bytes the application will accept; GetFontLore returns no more than that many bytes 
in the form of an initial segment of the font globals record. Thus, the application 
can avoid calling the Memory Manager to size a buffer on the basis of GetFGSize; 
instead, it can just receive the font globals information that the application knows 
how to handle. The GetFontLore routine is recommended; GetFontGlobals is 
maintained for compatibility reasons. 
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$0104 QDBooilnit 

Initializes QuickDraw H; called only by the Tool Locator. 

Warning 

An application must never make this call. 

This routine puts the address of the cursor update routine into the bank $E1 veaors. 
The stack is not affected by this call. There are no input or output parameters. 

None 

Call must not be made by an application. 


Parameters 

Errors 

C 
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$0204 


QDStartUp 

Starts up QuickDraw II for use by an application. 


Important 

Your application must make this call before it makes any other QuickDraw II 
calls. 


The routine sets the current port to the standard port and clears the screen. 

QuickDraw II uses three consecutive pages of bank zero for its direct page space, 
starting at dPageAddr. The maxWidth parameter specifies the size in bytes of the 
largest pixel map that will be drawn to (a value of 0 indicates screen width). Knowing 
this maxWidth allows QuickDraw II to allocate certain buffets only once and keep 
them throughout the life of the application. 


Parameters 


Stack before call 


previous contents 
dPageAddr 
masterSCB 
maxWidth 
userlD 


Word—Bank $0 starting address for 3 pages of direct-page space 
Word—^Master SCB for Super Hi-Res graphics 

Word—^INTEGER; size in bytes of largest pixel map, 0 for screen width 
Word—User ID of application 


SP 


Stack after call 


previous contents 


<—SP 


Errors 


$0401 

alreadyInitialized 

Attempt made to start up QuickDraw n a 
second time without first shutting it down 

$0410 

screenReserved 

Memory Manager reported screen memory 
(bank $E1 from $2000 to $9FFI0 is already 
owned by someone else 

Memory 

Manager errors 

Returned unchanged 
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C extern pascal void QDStartUp(dPageAddr,masterSCB,maxWldth,userID) 


Word 

dPageAddr; 

Word 

masterSCB; 

Word 

maxWidth; 

Word 

userlD; 
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$0304 QDShutDown 

Shuts down QuickDraw II when an application quits. 

Important 

If your application has started up QuickDraw II. the application must make this 
call before It quits. 

Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors Memory Manager errors Returned unchanged 

C extern pascal void QDShutDown() 


$0404 QDVersion 

Returns the version number of QuickDraw H. 

Parameters 


Stack before call 


previous contents 
wordspace 


Word —Space for result 
<—SP 


Stack after call 

previous contents 

versioninfo Word —^Version number of QuickDraw II 

<— SP 

Errors None 

C extern pascal Word QDVersion() 
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$0504 QDReset 

Resets QuickDraw II; called only when the system is reset 
Warning 

An application must never make this call. 

Parameters The stack is not affected by this call. There are no input or output parameters. 

Errors None 

C Call must not be made by an application. 


$0604 QDStatus 

Indicates whether QuickDraw II is active. 

Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

^SP 


Stack after call 

previous contents 

activeFlag Word—BOOLEAN; TRUE if QuickDraw n active, FALSE if inactive 

SP 

Errors None 

C extern pascal Boolean QDStatus() 
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$8004 AddPt 

Adds two specified points together and leaves the result in the destination point For 
example, two source points of (10,20) and (1,2) result in a destination point of 
( 11 , 22 ). 

Parameters 


Stack before call 
previous contents 


— 

srcPtPtr 

— 

-- 

destPtPtr 

— 


Long—POINTER to POINT 

Long—POINTER to POINT used as source and destination 
<— SP 


Stack after call 


previous contents 


<—SP 


Errors None 


C extern pascal void AddPt(srcPtPtr,destPtPtr) 

Point *srcPtPtr; 

Point *destPtPtr; 
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$AC04 CharBounds 

Places the character bounds rectangle of a specified character into a specified buffer. 

Parameters 

Stack before call 

previous contents 
theChar 

resultPtr 


Word—Character to use to set bounds 
Long— POINTER to space for rectangle 
<— SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void CharBounds(theChar,resultPtr) 

Word theChar; 

Rect *resultPtr; 
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$A804 CharWidth 

Returns the character width, in pixels (pen displacement), of a specified character. 

Parameters 

Stack before call 

previous contents 
wordspace 
theChar 


Word—Space for result 
Word—Character to be measured 
<—SP 


Stack after call 


previous contents 
charWidth 


Word—INTEGER; width of character in pixels 
<—SP 


Errors None 

C extern pascal Integer CharWidth(theChar) 

Word theChar; 
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$1504 ClearScreen 

Sets the words in screen memory to a specified value. The value is stuffed into each 
word of screen memory. The cohrWord value represents a group of adjacent pixels 
(4 in 320 mode; 8 in 640 mode). See the section “Drawing in Color” in this chapter. 
ClearScreen is usually used to clear the screen to a solid color. 


Parameters 

Stack before call 

previous contents 

colorWord Word—Color as offset into current color table 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void ClearScreen(colorWord) 

Word colorWord; 
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$2604 ClipRect 

Changes the clipping region of the current GrafPort to a rectangle that is equivalent to 
a specified rectangle. 

Parameters 

Stack before call 
previous contents 

rectPtr — Long— pointer to RECT defining rectangle 

<—SP 


Stack after call 
previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void ClipRect(rectPtr) 

Rect *rectPtr; 


$C204 ClosePoly 

Completes the polygon definition process started with an OpenPoly call 

Parameters The stack is not affected by this call. There are no input or output parameters. 

Errors $0441 PolyNotOpen No polygon open in current GrafPort 

Memory Manager errors Returned unchanged 

C extern pascal void ClosePoly() 
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$1A04 ClosePort 

Deallocates the dipping and visible regions in a port. If the application disposes of 
the memory containing the port without first calling ClosePort, the memory 
assodated with the handles is lost and cannot be redaimed. 


Warning 

Never close the current port. 

Parameters 

Stack before call 
previous contents 

portPtr — Long—POINTER to port 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void ClosePort(portPtr) 

GrafPortPtr portPtr; 
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$6E04 CloseRgn 

Completes the region-definition process started by an OpenRgn call. The region 
must have already been created by a NewRgn call, which supplies rgnHandle. 

Parameters 

Stack before call 
previous contents 

rgnHandle — Ix>ng—HANDLE to region being set to a collection of points 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors 


C 


$0431 rgnNotOpen No region open in current GrafPort 

Memory Manager errors Returned unchanged 

extern pascal void CloseRgn(rgnHandle) 

RgnHandle rgnHandle; 
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$6904 CopyRgn 

Copies the region definition from one region to another. The srcRgnHandle and 
destRgnHandle must have already been created; in particular, this routine does not 
allocate the destRgnHandle. 

Parameters 

Stack before call 

Long—HANDLE to source region 

Long—HANDLE to destination region 
<—SP 


previous contents 
— srcRgnHandle 


— destRgnHandle — 


Stack after call 
previous contents 


Errors 

C 


<— SP 


Memory Manager errors 


Returned unchanged 


extern pascal void CopyRgn(srcRgnHandle,destRgnHandle) 
RgnHandle srcRgnHandle; 

RgnHandle destRgnHandle; 
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$AE04 CStringBounds 

Places the character bounds rectangle of a specified C string into a specified buffer. 

Parameters 


Stack before call 

previous contents 


cStringPtr 

— 

resultPtr 

— 


Long—POINTER to C string 

Long—POINTER to space for rectangle 
4-SP 


Stack after call 


previous contents 


<-SP 


Errors None 

C extern pascal void CStringBounds(cStringPtr,resultPtr) 

Pointer cStringPtr; 

Rect *resultPtr; 
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$AA04 CStringWidth 

Returns the sum of all the character widths, in pixels (pen displacements), in a 
specified C string. This would be the pen displacement if the string were to be drawn. 

Parameters 


Stack before call 
previous contents 


wordspace 


cStringPtr 

— 


Word—Space for result 
Long—POINTER to C string 
<— SP 


Stack after call 
previous contents 

cStringWidth Word—INTEGER; width of C string in pixels 

<— SP 

Errors None 

C extern pascal Integer CStringWidth(cStringPtr) 

Pointer cStringPtr; 
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$7304 DiffRgn 

Calculates the difference of the areas enclosed by two regions and places the region 
definition of the enclosing area in a destination region. The destination region, 
which nuy be one of the source regions, must already exist; this routine does not 
allocate iL 

If the rgnlHandle is empty, the destination is set to an empty region. 


Parameters 

Stack before call 

Long—HANDLE to one source region 

Long—HANDLE to another source region 

Long—HANDLE to destination region 
<— SP 


previous contents 
— rgnlHandle 


rgn2Handle 


— diffRgnHandle — 


Stack after call 
previous contents 


Errors 

C 


SP 


Memory Manager errors 


Returned unchanged 


extern pascal void DiffRgn(rgnlHandle,rgnZHandle,diffRgnHandle) 
RgnHandle rgnlHandle; 

RgnHandle rgn2Handle; 

RgnHandle diffRgnHandle; 
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$6804 DisposeRgn 

Deallocates the memory for a specified region. For more information about how 
memory is allocated and deallocated, see Chapter 12, “Memory Manager,” in 
Volume 1. 


Parameters 

Stack before call 
previous contents 

rgnHandle — Long—HANDLE of region being disposed 

<—SP 


Stack after call 


previous contents 


SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void DisposeRgn(rgnHandle) 

RgnHandle rgnHandle; 
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$A404 


Parameters 


DrawChar 

Draws a specified character at the current pen location and updates the pen location. 


Stack before call 

previous contents 


theChar 


Word—ASCII code of character to be drawn (0-255) 
SP 


Stack after call 
previous contents 


Errors 

C 


SP 

None 

extern pascal void DrawChar(theChar) 
Word theChar; 


16-80 


QuickDraw II routines 












$A604 DrawCString 

Draws a specified C string at the current pen location and updates the pen location. 

Parameters 

Stack before call 

previous contents 

cStringPtr — Long—POINTER to C string 

4— SP 


Stack after call 


previous contents ' 


4— SP 


Errors None 

C extern pascal void DrawCString(cStringPtr) 

Pointer cStringPtr; 
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$A504 Drawstring 

Draws a specified Pascal-type string at the current pen location and updates the pen 
location. 

Parameters 

Stack before call 
previous contents 

stringPtr — Long—POINTER to Pascal-type string to be drawn 

<—SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void Drawstring(stringPtr) 

Pointer stringPtr; 
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$A704 DrawText 

Draws specified text at the current pen location and updates the pen location. 

Parameters 


Stack before call 

previous contents 
textPtr 
textLength 


Long—^POINTER to text to be drawn 

Word—^INTEGER; number of bytes in text to be drawn 
<-SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void DrawText(textPtr,textLength) 

Pointer textPtr; 

Word textLength; 
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$7804 EmptyRgn 

Indicates whether a specified region is empty. 

Parameters 

Stack before call 

previous contents 
wordspace 

— rgnHandle 


Word—Space for result 
Long—HANDLE to region 
<— SP 


Stack after call 


previous contents 
emptyFlag 


Word—^BOOLEAN; TRUE if region is empty, FALSE if not 
<—SP 


Errors None 


C 


extern pascal Boolean EmptyRgn(rgnHandle) 
RgnHandle rgnHandle; 
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$8304 EqualPt 

Indicates whether two points are equal (two equal points have the same Y and X 
coordinates). 

Parameters 


Stack before call 
previous contents 


wordspace 


pointlPtr 


point2Ptr 


Word —Space for result 
Long— POINTER to first POINT 

Long —POINTER to second POINT 
<— SP 


Stack after call 
previous contents 

equalFlag Word— ^BOOLEAN; TRUE if points are equal, FALSE if not 

<— SP 

Errors None 

C extern pascal Boolean EqualPt(pointlPtr,point2Ptr) 

Point *pointlPtr; 

Point *point2Ptr; 


QuickDraw II routines 


16-85 














$5104 EqualRect 

Indicates whether two rectangles are equal. The two rectangles must have identical 
sizes and locations to be considered equal. Any two empty rectangles are always 
equal. 

Parameters 


Stack before call 

previous contents 


wordspace 

rectlPtr 

— 

rect2Ptr 

— 


Word—Space for result 
Long—POINTER to RECT 

Long—POINTER to RECr 
<— SP 


defining one rectangle 
defining other rectangle 


Stack alter call 
previous contents 

equalFlag Word—^BOOLEAN; TRUE if rectangles are equal, FALSE if not 

^SP 

Errors None 

C extern pascal Boolean EqualRect(rectlPtr,rect2Ptr) 

Rect *rectlPtr; 

Rect *rect2Ptr; 
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$7704 EquaIRgn 

Indicates whether two regions are equal. TTie two regions must have identical sizes, 
shapes, and locations to be considered equal. Any two empty regions are always 
equal. 

Parameters 


Stack before call 

previous contents 
wordspace 

rgnlHandle 


Word—Space for result 
Long—HANDLE to one region 


rgn2Handle 


Long—HANDLE to other region 
<—SP 


Stack after call 
previous contents 


equalFlag 


Word—BOOLEAN; TRUE if regions are equal, FALSE if not 
<—SP 


Errors 

C 


Memory Manager errors 


Returned unchanged 


extern pascal Boolean EquaIRgn(rgnlHandle,rgnZHandle) 
RgnHandle rgnlHandle; 

RgnHandle rgn2Handle; 
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$6404 EraseArc 

Erases the interior of a specified arc by filling it with the background pattern. 

Parameters 

Stack before call 
previous contents 
rectPtr 

startAngle 
arcAngle 


Long—POINTER to RECT defining enclosing rectangle 

Word—^INTEGER; Starting angle in degrees 
Word—INTEGER; arc angle in degrees 
<— SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void EraseArc(rectPtr,startAngle,arcAngle) 

Rect *rectPtr; 

Integer startAngle; 

Integer arcAngle; 
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$5A04 EraseOvai 

Erases the interior of a specified oval by filling it with the background pattern. 

Parameters 

Stack before call 
previous contents 

rectPtr — Long—POINTER to RECT defining enclosing rectangle 

SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void EraseOvai(rectPtr) 

Rect *rectPtr; 
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$BE04 ErasePoly 

Erases the interior of a specified polygon by filling it with the background pattern. 
Because polygons are treated differently than other closed shapes, the frame of the 
polygon (if drawn) is not completely erased. See the section “Polygons” in this 
chapter for more information. 


Important 

Because this call allocates and deallocates some temporary memory space. 
Memory Manager errors can occur. 


Parameters 


Stack before call 

previous contents 
— polyHandle 


Long—HANDLE to polygon 
<—SP 


Stack after call 

previous contents I 

|<—SP 

Errors Memory Manager errors Returned unchanged 

C extern pascal void ErasePoly(polyHandle) 

Handle polyHandle; 
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$5504 EraseRect 

Erases the interior of a specified rectangle by filling it with the background pattern. 

Parameters 

Stack before call 
previous contents 

rectPtr — Long—POINTER to RECT defining rectangle 

<—SP 


Stack after call 


previous contents 


^SP 


Errors None 

C extern pascal void EraseRect(rectPtr) 

Rect *rectPtr; 
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$7B04 EraseRgn 

Erases the interior of a specified region by filling it with the background pattern. 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long—HANDLE to region 
SP 


Stack after call 
previous contents 


SP 


Errors 

C 


None 


extern pascal void EraseRgn(rgnHandle) 
RgnHandle rgnHandle; 
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$5F04 


EraseRRect 

Erases the interior of a specified round rectangle by filling it with the background 
pattern. 

The cornets of the round rectangle are sections of an oval defined by ovalHeight and 
ovalWidth. For mote information, see Figure 16-12 in the section “Rectangles” in 
this chapter. 


Parameters 


Stack before call 


previous contents 


rectPtr 


ovalWidth 

ovalHeight 


Long—POINTER to RECT defining enclosing rectangle 

Word—INTEGER; width, in pixels, of oval defining rounded corners 
Word—INTEGER; height, in pixels, of oval defining rounded corners 
^SP 


Stack after call 

previous contents I 

j<—SP 

Errors None 

C extern pascal void EraseRRect(rectPtr,ovalWidth,ovalHeight) 

Rect *rectPtr; 

Word ovalWidth; 

Word ovalHeight; 
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$6604 FillArc 

Fills the interior of a specified arc with a specified pen pattern. 

Parameters 

Stack before call 

previous contents 

— rectPtr 

startAngle 
arcAngle 

pattemPtr 


Long—POINTER to RECT defining rectangle 

Word—INTEGER; starting angle in degrees 
Word—INTEGER; arc angle in degrees 

Long—POINTER to pattern 

SP 


Stack after call 
previous contents 


4—SP 


Errors None 


C extern pascal void FillArc(rectPtr,startAngle,arcAngle,patternPtr) 

Rect *rectPtr; 

Integer startAngle; 

Integer arcAngle; 

Pattern patternPtr; 
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$5C04 FillOval 

Fills the interior of a specified oval with a specified pen pattern. 

Parameters 


Stack before call 


previous contents 


rectPtr 

— 

pattemPtr 

— 


Long—POINTER to RECT defining enclosing rectangle 

Long—POINTER to pattern 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void FillOval(rectPtr,patternPtr) 

Rect *rectPtr; 

Pattern patternPtr; 
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$C004 FillPoly 

Fills the interior of a specified polygon with a specified pen pattern. Because 
polygons are treated differently than other closed shapes, the frame of the polygon (if 
drawn) is not completely filled. See the section “Polygons” in this chapter for more 
information. 


Important 

Because this call allocates and deallocates some temporary memory space. 
Memory Manager errors can occur. 


Pararrieters 


Stack before call 
previous contents 
polyHandle 


Long—HANDLE to polygon 


pattemPtr 


Long—POINTER to pattern 
SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void FillPoly(polyHandle,patternPtr) 

Handle polyHandle; 

Pattern patternPtr; 
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$6704 


FillRect 

Fills the interior of a specified rectangle with a specified pen pattern. 


Parameters 


Stack before call 


previous contents 


rectPtr 

— 

pattemPtr 

— 


Long—POINTER to rectangle 

Long—POINTER to pattern 
SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void FillRect(rectPtr,patternPtr) 

Rect *rectPtr; 

Pattern patternPtr; 
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$7D04 FilIRgn 

Fills the interior of a specified region with a specified pen pattern. 

Parameters 


Stack before call 


previous contents 


rgnHandle 

— 

pattemPtr 

— 


Long—HANDLE to region 

Long—POINTER to pattern 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void FilIRgn(rgnHandle,patternPtr) 

RgnHandle rgnHandle; 

Pattern patternPtr; 
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$6104 FilIRRect 

Fills the interior of a specified round rectangle with a specified pen pattern. 

The comers of the round rectangle are sections of an oval defined by ovalHeight and 
ovalWidth. For more information, see Figure 16-12 in the section “Rectangles” in 
this chapter. 


Parameters 


Stack before call 
previous contents 
rectPtr 

ovalWidth 

ovalHeight 

pattemPtr 


Long—POINTER to RECT defining enclosing rectangle 

Word—INTEGER; width, in pixels, of oval defining rounded corners 
Word—INTEGER; height, in pixels, of oval defining rounded corners 

Long—POINTER to pattern 

4-SP 


Stack after call 
previous contents 


Errors 

C 


4- SP 


None 

extern pascal void FilIRRect(rectPtr,ovalWidth,ovalHeight,patternPtr) 
Rect *rectPtr; 

Word ovalWidth; 

Word ovalHeight; 

Pattern patternPtr; 
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$CC04 ForceBufDims 

Sets the si 2 e of the QuickDraw II clipping and text buffers, but does not pad 
maxFBRExtent in any way. The maxFBRExtent value must include not only the 
greatest width of the character but also any extra width necessary because of style 
modifications, chExtra, and spExtra. 

»J* Note: You need to make this call only if your application is going to use, or allow 
the user to choose, fonts that have unusually large values of chExtra and ^Extra. 
See the section “Fonts and Text in QuickDraw H” in this chapter for more 
information. 

Although SetBufDims and ForceBufDims may be called at any time, it is usually best 
to call them once with reasonable maximum values early in the application (if at all), 
because claiming and clearing a buffer can take lots of time. 

Parameters 


Stack before call 


previous contents 
maxWidth 
maxFontHeight 
maxFBRExtent 


Word—INTEGER; width, in bytes, of widest pixel map to be used 
Word—INTEGER; height, in pixels, of tallest font the application will use 
Word—INTEGER; greatest fbrExtent in pixels of any font to be used 


SP 


Stack after call 


previous contents 


SP 


Errors Memory Manager errors Returned unchanged 


C 


extern pascal void ForceBufDims(maxWidth,maxFontHeight,maxFBRExtent) 
Word maxWidth; 

Word maxFontHeight; 

Word maxFBRExtent; 
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$6204 FrameArc 

Draws the frame of a specified arc using the current pen mode, pen pattern, and pen 
size. Only pixels entirely within the rectangle are affected. 


Parameters 

Stack before call 

Long—POINTER to RECT defining enclosing rectangle 

Word—INTEGER; Starting angle in degrees 
Word—INTEGER; arc angle in degrees 
<—SP 


previous contents 


rectPtr 


startAngle 

arcAngle 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void FrameArc(rectPtr,startAngle,arcAngle) 

Rect *rectPtr; 

Integer startAngle; 

Integer arcAngle; 
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$5804 FrameOval 

Draws the frame of a specified oval using the current pen mode, pen pattern, and pen 
size. Only pixels entirely within the rectangle are affected. 


Important 

If a region is open, this command contributes to the region definition; this can 
cause Memory Manager errors to occur. 


Parameters 

Stack before call 
previous contents 

rectPtr — Long—POINTER to RECT defining enclosing rectangle 
<—SP 


Stack after call 


previous contents 


<—SP 


EffOiS Memory Manager errors Returned unchanged 

C extern pascal void FrameOval(rectPtr) 

Rect rectPtr; 
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$BC04 FramePoly 

Draws the frame of a specified polygon using the current pen mode, pen pattern, and 
pen si 2 e. The polygon is framed with a series of LineTo calls. 


Important 

If this call Is used, parts of the frame are not affected by ErasePoly and FillPoly 
calls. You can, for example, erase the frame by using another FramePoly call 
using the background pattern. In addition. If a region Is open, this command 
contributes to the region definition; this can cause Memory Manager errors to 
occur. 


Parameters 


Stack before call 


previous contents 
— polyHandle 


Long—HANDLE to polygon 


<— SP 


Stack after call 


previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void FramePoly(polyHandle) 

Handle polyHandle; 
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$5304 FrameRect 

Draws the frame of a specified rectangle using the current pen mode, pen pattern, 
and pen size. Only pixels entirely within the rectangle are affected. 


Important 

If a region Is open, this command contributes to the region definition; this can 
cause Memory Manager errors to occur. 


Parameters 

Stack before call 
previous contents 

rectPtr — Long—POINTER to RECT defining rectangle 

<-SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void FrameRect(rectPtr) 

Rect *rectPtr; 
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$7904 FrameRgn 

Draws the frame of a specified region using the current pen mode, pen pattern, and 
pen size. Only pixels entirely inside the region are affected. 

If a region is open and being formed, the outline of the region being framed is added 
to the open region’s boundary. 


Important 

If a region is open, this command contributes to the region definition; this can 
cause Memory Manager errors to occur. 


Parameters 

Stack before call 
previous contents 

rgnHandle — Long —handle to region 

4-SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void FrameRgn(rgnHandle) 

RgnHandle rgnHandle; 
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$5D04 FrameRRect 

Draws the frame of a specified round rectangle using the current pen mode, pen 
pattern, and pen size. Only pixels entirely within the rectangle are affected. 


Important 

If a region Is open, this command contributes to the region definition; this can 
cause Memory Manager errors to occur. 


The comers of the round rectangle are sections of an oval defined by ovalHeight and 
ovalWidth. For more information, see Figure 16-12 in the section “Rectangles” in 
this chapter. 

Parameters 


Stack before call 


previous contents 


rectPtr 


Long—POINTER to RECT defining enclosing rectangle 


ovalWidth 

ovalHeight 


Word—INTEGER; width, in pixels, of oval defining rounded corners 
Word—INTEGER; height, in pixels, of oval defining rounded corners 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void FrameRRect(rectPtr,ovalWidth,ovalHeight) 

Rect *rectPtr; 

Word ovalWidth; 

Word ovalHeight; 
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$0904 GetAddress 

Returns a pointer to a specified table. QuickDraw n contains a number of tables that 
may be useful. The GetAddress call allows you to access these tables. 

The current tablelDs are as follows: 

$0001 screenTable 
$0002 conTable320 
$0003 conTable640 


Important 

If your application is using one of these tables, make sure the application obtains 
the correct pointer every time it runs. These tables will move as the ROM 
version changes. 


The screen table has 200 two-byte entries. Each entry is the address of the start of a 
scan line in the display buffer. The zeroth entry is $2000, which is the address of scan 
line 0; entry 1 is $20A0, which is the address of scan line 1; and so on. 

The conTable320 and conTable640 tables are used to convert from bytes that are 
one bit per pixel to bytes that are four and two bits per pixel respectively. The 
conTable320 table has 256 four-byte entries; the conTable640 table has 256 two- 
byte entries. These entries are the two- and four-bit-per-pixel representations of one- 
bit-per-pixel bytes. 


Parameters 


Stack before call 
previous contents 


— 

longspace 

— 

tablelD 


Long—Space for result 

Word—INTEGER; ID of table whose 
<—SP 


pointer will be retrieved 


Stack after call 


previous contents 


tablePtr 


Long—POINTER to table in ROM 
<—SP 
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Errors 


None 


C extern pascal Pointer GetAddress(tablelD) 

Word tablelD; 


Assembly-language example 

The byte containing $37 appears as follows in one-, two-, and four-bit-per-pixel 
mode: 

One-bit Two-bit Four-bit 

%oonoiii %oo 0011 1100 ii ii ii $ooff offf 

The two- and four-bit versions would be obtained from the table as follows: 


Ida OneBit 

Ida OneBit ; Pick up the byte 

and #$00FF 

and #$00FF ; Mask off the high byte 

asl a 

asl a ; Multiply by 2 or 4 

tay 

asl a 

Ida [TwoBitTable],y 

tay ; Put result in y 

Ida [FourBitTable],y ; Load out of table through y 

tax ; Save in x 

iny ; Bump y 

iny 

Ida [FourBitTable],y ; Get the second word 


In both cases, the addresses obtained from GetAddress are already on the direct 
page. 
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$B104 GetArcRot 

Returns the value of the arcRot field in the current GrafPort. 

Parameters 

Stack before call 
previous contents 

wordspace Word—^Space for result 

<— SP 


Stack after call 


previous contents 
arcRot 


Word—INTEGER; value of arcRot field 
<— SP 


Errors None 

C extern pascal Integer GetArcRot() 
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$A304 GetBackColor 

Returns the value of the bgColorTield from the GrafPort. 

Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

SP 


Stack after call 
previous contents 

backColor Word—INTEGER; value of fcgCotor field 

SP 

Errors None 

C extern pascal Word GetBackColor<) 
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$3504 GetBackPat 

Copies the current background pen pattern from the current GrafPort to a specified 
location. 

Parameters 

Stack before call 

previous contents 

pattemPtr — Long— pointer to location for pattern 

<—SP 


Stack after call 

previous contents I 

<—SP 


Errors None 

C extern pascal void GetBackPat(patternPtr) 

Pattern patternPtr; 
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$D504 GetCharExtra 

Returns the chExtra field from the GrafPort. 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

<— SP 


Stack after call 
previous contents 

charExtra — Long—FIXED; value of chExtra field 

SP 

Errors None 

C extern pascal Fixed GetCharExtra() 
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$2504 GetClip 

Copies the dipping region to a spedfied region. The destination region must have 
been created earlier with a NewRgn call. 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long—HANDLE to region 
SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void GetClip(rgnHandle) 

RgnHandle rgnHandle; 
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$0704 GetClipHandle 

Returns a copy of the handle to the dipping region. 

Parameters 

Stack before call 

previous contents 

longspace — Long—Space for result 

<— SP 


Stack after call 
previous contents 
rgnHandle 


Long—HANDLE to dipping region 
<—SP 


Errors None 

C extern pascal RgnHandle GetClipHandle() 


16-114 QuickDraw II routines 












$1104 GetColorEntry 

Returns the value of a specified color in a specified color table. 

Parameters 


Stack before call 


previous contents 
wordspace 
tableNumber 
entryNumber 


Word—Space for result 
Word— INTEGER; number of color table 
Word— INTEGER; number of color to be examined 
<—SP 


Stack after call 


previous contents 
color 


Word—Color of entry 
SP 


Errors $0450 badTableNum Invalid table number; 0 to 15 are valid 

$0451 badColorNum Invalid color number; 0 to 15 are valid 

C extern pascal Word GetColorEntry(tableNumber,entryNumber) 

Word tableNumber; 

Word entryNumber; 
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$0F04 GetColorTable 

Fills a specified color table with the contents of another color table. 

Parameters 


Stack before call 

previous contents 
tableNumber 


destTablePtr 


Word —INTEGER; color table to be copied 
Long —POINTER to color table to receive new values 
<—SP 


Stack after call 


previous contents 


<r- SP 


Errors $0450 badTableNum Invalid table number; 0 to 15 are valid 

C extern pascal void GetColorTable(tableNumber,destTablePtr) 

Word tableNumber; 

ColorTable destTablePtr; 
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$8F04 


Parameters 


GetCursorAdr 

Returns a pointer to the current cursor record See the section “Cursors” in this 
chapter for the definition of the cursor record. 


Stack before call 

previous contents 


longspace 


Long—Space for result 
<—SP 


Stack after call 

previous contents 


cursorPtr 


Errors 

C 


Long—POINTER to current cursor record 
SP 

None 

extern pascal Pointer GetCursorAdr() 
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$CF04 


GetFGSize 

Returns the size of the font globals record. The font globals record, which contains 
information about the font, may increase in length in future versions of QuickDraw II. 
The GetFGSize routine tells your application how much space to allocate for the 
record. 

This call is primarily intended to provide backward compatibility. Under normal 
circumstances, you’ll probably prefer to use the GetFontLoie routine. See the section 
“GetFontLore” in this chapter. 

❖ Note: The information in the record will only increase. Fields that have been 
defined will not disappear, but additional fields may be added at the end of the 
font globals record. 


Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

<— SP 


Stack after call 


previous contents 
fgSize 


Word—INTEGER; size of font globals record 
<— SP 


Errors None 

C extern pascal Word GetFGSize() 
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$9504 GetFont 

Returns a handle to the current font. 

Parameters 

Stack before call 
previous contents 


longspace — Long—Space for result 

<— SP 


Stack after call 
previous contents 

— fontHandle — Long—HANDLE to font 

SP 

Errors None 

C extern pascal FontHndl GetFont() 
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$9904 GetFontFlags 

Returns the current font flags word. See Figure 16-37 in the section “SetFontFlags” in 
this chapter for the possible fontFlags values. 


Parameters 

Stack before call 
previous contents 

wordspace Word—Space for result 

SP 


Stack after call 


previous contents 
fontFlags 


Word—^INTEGER; current font flags word (see Figure 16-37) 
SP 


Errors None 

C extern pascal Word GetFontFlags() 
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$9704 GetFontGlobals 

Returns information about the font globals record into a specified buffer. The size of 
the font globals record is returned by the GetFGSize routine, as described in the 
section “GetFGSize” in this chapter. The information represents the GrafPort’s 
current font and does not reflect style modifications, chExtra or spExtra fields, and 
so on. Future versions of QuickDraw II may add more information at the end of this 
record, but the current fields and their order will be maintained. 

This call is primarily intended to provide backward compatibility. Under normal 
circumstances, you’ll probably prefer to use the GetFontLore routine. See the section 
“GetFontLore” in this chapter. 


Parameters 

Stack before call 
previous contents 

fgRecPtr — l<ong—POINTER to space for font globals record 

4- SP 


Stack after call 


previous contents 


<— SP 


Errors None 


C 


extern pascal void GetFontGlobals(fgRecPtr) 
FontGlobalsRecPtr fgRecPtr; 
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$D104 GetFontID 

Returns the fontID field of the GrafPort. 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

<— SP 


Stack after call 


previous contents 


fontID 


Long—^Value of fontID field in GrafPort 


<—SP 


Errors None 

C extern pascal LongWord GetFontID{) 

❖ Note: C Pascal-type functions do not deal properly with data structures returned 
on the stack. The Long result returned by this call can be passed to any calls 
requiring a font ID as a parameter. You cannot use the C dot operator to access the 
individual font ID fields within the value returned by this call. 
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$9604 GetFontInfo 

Returns information about the current font in a specified buffer. The information in 
the fontinfo record does reflect current style modifications, but not the values of the 
chExtra and spExtra fields of the GrafPort. See the section “Font Information Calls” 
in this chapter for the definition of the font info record. 

Your application can use the information returned in the fontinfo record to 
determine the spacing between lines of text. Normal spacing is ascent plus descent 
plus leading. 


Parameters 

Stack before call 
previous contents 

— fontInfoRecPtr — Long—POINTER to space for fontinfo record 

<—SP 


Stack after caU 


previous contents 


SP 


Errors None 

C extern pascal void GetFontInfo(fontInfoRecPtr) 

FontInfoRecPtr fontInfoRecPtr; 
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$D904 GetFontLore 

Returns information, up to a specified number of bytes, about the current font in a 
specified buffer. The routine returns the same values as the GetFontGlobals call (see 
the section “Font Information Calls” in this chapter), except that GetFontLore will not 
return more bytes than are specified in the recordSize parameter. Thus, you can set 
aside a fixed amount of space for the record. 


Important 

This call Is available In Version 2.0 or later of QuickDraw II. 


You can specify the number of bytes as equal to the maximum number of bytes in the 
record for a particular version of QuickDraw H. Future versions of QuickDraw II may 
add more information at the end of this record, but the current fields and their order 
will be maintained. 

The numBytesXferv^ne may sometimes be less than recordSize—iox example, if the 
recordSize is larger than the number of bytes that GetFontLore has to return. 


Parameters 

Stack before call 

previous contents 
wordspace 

recordPtr 

recordSize 


Word—Space for result 

Long—POINTER to space for record 

Word—Maximum number of bytes to transfer 
<—SP 


Stack after call 
previous contents 

numBytesXfer Word—INTEGER; number of bytes transferred 

<—SP 

Errors None 

C extern pascal Word GetFontLore(recordPtr,recordSize) 

FontGlobalsRecPtr recordPtr; 

Word recordSize; 
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$A104 GetForeColor 

Returns the value of the current ^Cotor field from the GrafPort. 

Parameters 

Stack before call 

previous contents 
wordspace 

Stack after call 
previous contents 

foreColor Word—INTEGER; value of ^Co/or field 

SP 

Errors None 

C extern pascal Word GetForeColor() 


Word—Space for result 
4- SP 
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$4504 GetGrafProcs 

Returns the pointer to the grafProcs record associated with the GrafPort 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

<—SP 


Stack after call 
previous contents 

— graJProcsPtr — Long—POINTER to grafProcs record 

<—SP 

Errors None 

C extern pascal QDProcsPtr GetGrafProcs() 
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$1704 GetMasterSCB 

Returns a copy of the master SCB. 

Parameters 

Stack before call 

previous contents 
wordspace 

Stack after call 

previous contents 

masterSCB Word—Master SCB value 

<— SP 

Errors None 

C extern pascal Word GetMasterSCB() 


Word—Space for result 
<— SP 
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$2904 GetPen 

Returns the pen location. 

❖ Macintosh programmers: This routine does not pass the point on the stack; 
instead, it passes a pointer to the point 

Parameters 

Stack before call 

previous contents 

pointPtr — Long—POINTER to POINT 
SP 


Stack after call 


previous contents 


<r-SF 


Errors None 

C extern pascal void GetPen(pointPtr) 

Point *pointPtr; 
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$3304 GetPenMask 

Returns the pen mask to a specified location. 

Parameters 

Stack before call 

previous contents 

maskPtr — Long—POINTER to space for mask 

SP 


Stack after call 


previous contents 


<—SP 


Errors None 


C 


extern pascal void GetPenMask(maskPtr) 
Mask maskPtr; 
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$2F04 GetPenMode 

Returns the pen mode from the current GrafPorL See Table l6-9 in the section 
“SetPenMode” in this chapter for the pen mode values. 


Parameters 

Stack before call 

previous contents 

wordspace Word —^Space for result 

SP 


Stack after call 

previous contents 

penMode Word —INTEGER; pen mode value, as shown in Table l6-9 

^SP 

Errors None 

C extern pascal Word GetPenMode() 


T'6-130 QuickDraw II routines 













$3104 , GetPenPat 

Copies the current pen pattern from the current GrafPort to a specified location. 

Parameters 

Stack after call 
previous contents 

pattemPtr — Long—POINTER to space for pattern 

<—SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void GetPenPat(patternPtr) 

Pattern patternPtr; 
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$2D04 GetPenSize 

Returns the current pen si2e to a specified location. 

Parameters 

Stack before call 
previous contents 

pointPtr — Long—POINTER to space for POINT 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void GetPenSize(pointPtr) 

Point *pointPtr; 
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$2B04 


Parameters 


GetPenState 

Returns the pen state from the GrafPort to a specified location. See Figure 16-38 in the 
section “SetPenState” in this chapter for the definition of the pen state record. 


Stack before call 
previous contents 


penStatePtr 


Long—POINTER to space for pen state record 
^ SP 


Stack after call 
previous contents 


k-sp 


Errors 

C 


None 

extern pascal void GetPenState(penStatePtr) 
PenStatePtr penStatePtr; 
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$3F04 GetPicSave 

Returns the value of the picSave field of the GrafPort. 

Parameters 

Stack before call 

previous contents 

longspace — Long—Space for result 

<— SP 


Stack after call 

previous contents 

— picSaveValue — Long—Current picSave value 

<— SP 


Errors None 

C extern pascal Longint GetPicSave() 
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$8804 GetPixel 

Returns the pixel below and to the right of a specified point. 

The thePixel result is returned in the lower bits of the word. If the current drawing 
location has a chunkiness of 2, two bits of the word are valid. If the current drawing 
location has a chunkiness of 4, four bits of the word are valid. 

There is no guarantee that the point actually belongs to the port 


Parameters 
Stack before call 


Word—Space for result 

Word—Horizontal value of point, in global coordinates 
Word—^Vertical value of point, in global coordinates 
<—SP 



Stack after call 


previous contents 
thePixel 


Word—^Pixel value 
4— SP 


Errors None 

C extern pascal Word GetPixel(h,v) 

Integer h; 

Integer v; 

You can also use the following alternate form of the call; 
extern pascal Word GetPixel(point) 

Point point; 
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$4304 GetPolySave 

Returns the value of the polySave field of the GrafPoit. 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

<—SP 


Stack after call 
previous contents 

— polySaveValue — Long—Current polySave value 

SP 


Errors None 

C extern pascal LongWord GetPolySave<) 
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$1C04 GetPort 

Returns a pointer to the current GrafPort 

Parameters 

Stack before call 

previous contents 

longspace — Long—Space for result 
<—SP 


Stack after call 
previous contents 

resultPtr — Long—POINTER to GrafPort 

SP 

Errors None 

C extern pascal GrafPortPtr GetPort() 
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$)E04 GetPortLoc 

Gets the current port’s locinfo record and puts it at the specified location. 

Parameters 

Stack before call 
previous contents 

locInfoPtr — Long—POINTER to space for locinfo record 

SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void GetPortLocdocInfoPtr) 

LocInfoPtr locInfoPtr; 
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$2004 GetPortRect 

Returns the current GrafPort’s port rectangle. 

Parameters 

Stack before call 
previous contents 

rectPtr — Long —pointer to space for RECT defining rectangle 

SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void GetPortRect(rectPtr) 

Rect *rectPtr; 
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$4104 GetRgnSave 

Returns the value of the rgnSave field of the GrafPort 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

<— SP 


Stack after call 
previous contents 


— rgnSaveValue — 


Long—Current rgnSave 
SP 


Errors None 

C extern pascal LongWord GetRgnSave<) 
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$D804 GetRomFont 

Fills a specified buffer with information about the font in ROM. 

Parameters 

Stack before call 
previous contents 

recordPtr — Long—POINTER to space for ROM font record (see Figure 16-33) 

<-SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void GetROMFont(recordPtr) 

RomFontRecPtr recordPtr; 


(continued) 
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The record 

The record pointed to by recordPtrhSiS the form illustrated in Figure 16-33. 


Offset Field 

Word—INTEGER specifying font family number 
Word—Specifying font style 
Word—INTEGER specifying font size In points 

Long-HANDLEtofont 

Long—POINTER to font name 

Word-INTEGER indicating fbrExtent 

Figure 16-33 

ROM font record 


$0 

1 

2 

3 

4 

5 

6 

7 

8 
9 
A 
B 
C 
D 
E 
F 


— rfFamNum — 


— rfFamStyle — 


— rfSize — 


— rfFontHandle — 


— rfNamePtr — 


rfFbrExtent — 
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$1304 GetSCB 

Returns the value of a specified SCB (scan line control byte). 

Parameters 


Stack before call 


previous contents 
wordspace 
scanLine 


Word—Space for result 

Word—INTEGER; scan line whose SCB is to be examined 

SP 


Stack after call 

Word—Value of SCB 
^SP 

Errors $0452 badScanLine Invalid scan line number; 0 to 199 are valid 

C extern pascal Word GetSCB(scanLine) 

Word scanLine; 


previous contents 
scb 
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$9F04 GetSpaceExtra 


Returns the value of the spExtra field from the GrafRort. 


Parameters 


Stack before call 

previous contents 


longspace 


Long—Space for result 
<—SP 


Stack after call 
previous contents 


spaceExtra 


Errors 

C 


Long—FIXED; value of spExtra field 
«-SP 

None 

extern pascal Fixed GetSpaceExtra0 
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$0C04 GetStandardSCB 

Returns a copy of the standard SCB in the low-order byte of the word. 

Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

^SP 


Stack after call 


previous contents 
scb 


Word—Standard SCB (see Figure 16-34) 
<—SP 


Errors None 

C extern pascal Word GetStandardSCB() 


Standard SCB 

The standard SCB has values as shown in Figure 16-34. 


Mtuftafiitll|lO|9|8|7|6|s|4|3|2[ l|o 


Reserved; set to 0 

Color table 320 = 0 

Interrupt off = 0 
Color fill mode off = 0 
Reserved for future use 

Color table 0 = 0000 


I L 


Figure 16-34 

Standard SCB 
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$4904 GetSysField 

Returns the value of the sysF^ld field of the GrafPort 

Parameters 

Stack before call 

previous contents 

longspace — Long—Space for result 

<—SP 


Stack after call 


previous contents 


sysField 


Long—Current sysField value 
<—SP 


Errors None 

C extern pascal Longint GetSysField() 
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$B304 GetSysFont 

Returns a handle to the current system font. 

Parameters 


Stack before call 

previous contents 


longspace 


Long—Space for result 
<—SP 


Stack after call 
previous contents 


— fontHandle 


Errors 

C 


Long—HANDLE to current system for 
<—SP 

None 

extern pascal FontHndl GetSysFont() 
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$9B04 GetTextFace 

Returns the current text face. See Figure 16-39 in the section “SetTextFace” in this 
chapter for the bit values for the textFace parameter. 


Parameters 


Stack before call 


previous contents 
wordspace 


Word—Space for result 
<—SP 


Stack after call 


previous contents 
textFace 


Word— INTEGER; text face (see Figure 16-39 in “SetTextFace”) 

SP 


Errors None 

C extern pascal TextStyle GetTextFace0 


16-148 QuickDraw II routines 













$9D04 GetTextMode 

Returns the current text mode. See Table 16-10 in the section “SetTextMode” in this 
chapter for the modes used only for text. 

Parameters 

Stack before call 

previous contents 
wordspace 


Word—Space for result 
SP 


Stack after call 


previous contents 
textMode 


Word—INTEGER; text mode (see Table 16-10 in “SetTextMode”) 

<— SP 


Errors None 

C extern pascal Word GetTextMode() 
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$D304 GetTextSize 

Returns the current value of the IxStze field of the GrafPort This value may not be the 
same as the point size of the current font; to obtain that value, use the GetFontLore or 
GetFontGlobals routines. 


Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

SP 


Stack after call 


previous contents 
textSize 


Word—Current value of txSize field 
<— SP 


Errors None 

C extern pascal Integer GetTextSize() 
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$4704 GetUserField 

Returns the value of the userField field of the GrafPort. 

Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 
<—SP 


Stack after call 


previous contents 


userField 


Long—Current userField value 
SP 


Errors None 

C extern pascal Longint GetOserFleldO 
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$C904 GetVi$Handle 

Returns a copy of the handle to the visible region. 

Parameters 


Stack before call 
previous contents 


longspace 


Long—Space for result 
<—SP 


Stack after call 
previous contents 


— visRgnHandle 


Errors 

C 


Long—HANDLE to region 
SP 

None 

extern pascal RgnHandle GetVlsHandle() 
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$B504 GetVisRgn 

Copies the contents of the visible region into a specified region. The region must 
have already been created with a NewRgn call. 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long— handle to region 

<— SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void GetVisRgn(rgnHandle) 

RgnHandle rgnHandle; 
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$8504 GlobalToLocal 

Converts a point from global coordinates to local coordinates. Global coordinates 
have 0,0 as the upper left corner of the pbcel image. Local coordinates are based on 
the current boundary rectangle of the GrafPort. 

Parameters 


Stack before call 

previous contents 
pointPtr 


Long—POINTER to POINT to be converted 
<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void GlobalToLocal(pointPtr) 

Point *pointPtr; 
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$0B04 

GrafOff 

Turns off the Super Hi-Res graphics mode. The routine affects only the bit in the New 
Video register that affects what is displayed. It does not change the linearization bit in 
the field. See the Apple IIGS Hardware Reference for more information. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void GrafOff() 


$0A04 

GrafOn 

Turns on the Super Hi-Res graphics mode. The routine affects only the bit in the New 
Video register that affects what is displayed. It does not change the linearization bit in 
the field. See the Apple IIGS Hardware Reference for more information. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void GrafOn() 
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$9004 

HideCursor 

Hides the cursor by decrementing the cursor level. A cursor level of 0 indicates the 
cursor is visible; a cursor level less than 0 indicates the cursor is not visible. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void HideCursor() 


$2704 

HidePen 

Decrements the pen level. A non-negative pen level indicates that drawing will 
occur; a negative pen level indicates that drawing will not occur. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void HidePen() 
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$D704 InflateTextBuffer 

Ensures that the text buffer is big enough to handle a font with the specified width and 
height, inaeasing it if necessary. 

This routine is usually used only by the Font Manager, but you may need it if your 
application is dealing with fonts without the Font Manager’s help. 


Parameters 


Stack before call 


previous contents 
newWidth 
newHeight 


Word—INTEGER; width of font 
Word—INTEGER; height of font 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 


C extern pascal void InflateTextBuffer(newWidth,newHeight) 

Word newWidth; 

Word newHeight; 
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$0D04 InitColorTable 

Returns a copy of the standard color table for the current mode, as shown in 

Table l6-7. 

Parameters 

Stack before call 

previous contents 

tablePtr — Long — pointer to space for standard color table (see Table l6-7) 

^SP 


Stack after call 

previous contents I 

j«—SP 

Errors None 

C extern pascal void InitColorTable(tablePtr) 

ColorTable tablePtr; 
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standard color tables 

The standard color tables are shown in Table l6-7. 


Table 16-7 

Standard color tables 


Pixel 

value 

Name 

Master 

color 

Pixel 

value 

Name 

Master 

color 

Entries for 320 mode 


Entries for 640 mode 


0 

Black 

000 

0 

Black 

000 

1 

Dark gray 

111 

1 

Red 

FOO 

2 

Brown 

841 

2 

Green 

OFO 

3 

Purple 

72C 

3 

White 

FFF 

4 

Blue 

OOF 

4 

Black 

000 

5 

Dark green 

080 

5 

Blue 

OOF 

6 

Orange 

F70 

6 

Yellow 

FFO 

7 

Red 

DOO 

7 

White 

FFF 

8 

Beige 

FA9 

8 

Black 

000 

9 

Yellow 

FFO 

9 

Red 

FOO 

10 

Green 

OEO 

A 

Green 

OFO 

11 

Light blue 

4DF 

B 

White 

FFF 

12 

Lilac 

DAF 

C 

Black 

000 

13 

Periwinkle blue 

78F 

D 

Blue 

OOF 

14 

Light gray 

ccc 

E 

Yellow 

FFO 

15 

White 

FFF 

F 

White 

FFF 
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$CA04 

InitCursor 

Reinitializes the cursor. The cursor is set to the arrow cursor and made visible. 

This routine also checks the master SCB and sets the cursor accordingly. Use this 
routine if you want to change modes in the middle of a program. The steps you take to 
do this are 

1 . Hide the cursor if it is not already hidden. 

2 . Set the master SCB to the mode you want. 

3 . Set all the SCBs to the master SCB. 

4. Set the color table the way you want it. 

5. Repaint the screen for the new mode. 

6. Call InitCursor. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void InitCursor () 
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$1904 InitPort 

Initializes specified memory locations as a standard port. 

InitPort, unlike the OpenPort routine, assumes that the region handles are valid and 
does not allocate new handles. Otherwise, InitPort performs the same functions as 
OpenPort. 


Parameters 

Stack before call 

previous contents 


portPtr — Long—POINTER to port 

<— SP 


Stack after call 


previous contents 


SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void InitPort(portPtr) 

GrafPortPtr portPtr; 
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$4004 InsetRect 

Insets a specified rectangle by specified displacements. The value specified as dH is 
added to the left and subtracted from the right; the value specified as dV\s added to 
the top and subtracted from the bottom. 

Parameters 


Stack before call 



Long—POINTER to rectangle 

Word—INTEGER; horizontal displacement 
Word—INTEGER; vertical displacement 
<— SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void InsetRect(rectPtr,dH,dV) 

Rect *rectPtr; 

Integer dH; 

Integer dV; 
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$7004 InsetRgn 

Shrinks or expands a specified region. All points on the region boundary are moved 
inward a distance of aW horizontally and dVvertically. If dHor dV'ts negative, the 
points are moved outward in that direction. InsetRgn leaves the region centered on 
the same position but moves the outline. InsetRgn of a rectangular region works just 
like InsetRect. 


Parameters 


Stack before call 



Long—HANDLE to region being inset 

Word—INTEGER; horizontal displacement 
Word—INTEGER; vertical displacement 
SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 


C 


extern pascal void InsetRgn(rgnHandle,dH,dV) 

RgnHandle 

rgnHandle; 

Integer 

dH; 

Integer 

dV; 


QuickDraw 


routines 16-163 














$6504 InvertArc 

Inverts the pixels in the interior of a specified arc. 

Parameters 


Stack before call 


previous contents 


rectPtr 


Long—POINTER to RECT specifying enclosing rectangle 


startAngle 

arcAngle 


Word—INTEGER; Starting angle in degrees 
Word—INTEGER; arc angle in degrees 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void InvertArc(rectPtr,startAngle,arcAngle) 

Rect *rectPtr; 

Integer startAngle; 

Integer arcAngle; 
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$5B04 InvertOval 

Inverts the pixeb in the interior of a specified oval. 

Parameters 

Stack before call 
previous contents 

rectPtr — Long —pointer to RECT spedlying enclosing rectangle 

<— SP 


Stack after call 

previous contents j 

|<—SP 

Errors None 

C extern pascal void InvertOval(rectPtr) 

Rect *rectPtr; 
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$BF04 InvertPoly 

Inverts the pixels in the interior of a specified polygon. The polygon is inverted by 
opening a region, drawing lines, dosing the region, and inverting the region. 


Important 

Because this call allocates and deallocates some temporary memory space. 
Memory Marxiger errors can occur. 


Parameters 

Stack before call 
previous contents 

polyHandle — Long —handle to polygon 

<— SP 


Stack after call 
previous contents 


<-SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void InvertPoly(polyHandle) 

Handle polyHandle; 
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$5604 InvertRect 

Inverts the pixels in the interior of a specified rectangle. 

Parameters 

Stack before call 

previous contents 

rectPtr — Long—POINTER to RECT specifying rectangle 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void InvertRect(rectPtr) 

Rect *rectPtr; 
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$7C04 InvertRgn 

Inverts the pixels in the interior of a specified region. 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long —handle to region 
SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void InvertRgn(rgnHandle) 

RgnHandle rgnHandle; 


16-168 QuickDraw II routines 












$6004 InvertRRect 

Inverts the pixels in the interior of a specified round rectangle. 

The corners of the round rectangle are sections of an oval defined by ovalHeight and 
ovalWidth. For more information, see Figure 16-12 in the section “Rectangles” in 
this chapter. 


Parameters 
Stack before call 

Long—POINTER to RECT specifying enclosing rectangle 

Word—INTEGER; width, in pixels, of oval defining rounded corners 
Word—INTEGER; height, in pixels, of oval defining rounded corners 
<— SP 


previous contents 


rectPtr 


ovalWidth 

ovalHeight 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void InvertRRect(rectPtr,ovalWidth,ovalHeight) 

Rect *rectPtr; 

Word ovalWidth; 

Word ovalHeight; 
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$C304 KillPoly 

Disposes of a specified polygon. 

Parameters 


Stack before call 
previous contents 
— polyHandle 


Long—HANDLE to polygon to be killed 
<— SP 


Stack after call 

previous contents I 

\<r- SP 

Errors Memory Manager errors Returned unchanged 

C extern pascal void KillPoly(polyHandle) 

Handle polyHandle; 
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$3D04 Line 

Draws a line from the current pen location to a new point specified by the horizontal 
and vertical displacements. 


Important 

If a region Is open, this command contributes to the region definition; this can 
cause Memory Manager errors to occur. 


Parameters 

Stack before call 

previous contents 


Word —INTEGER; horizontal displacement in points 
Word —INTEGER; vertical displacement in points 
<— SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void Line{dH,dV) 

Integer dH; 

Integer dV; 
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$3004 LineTo 

Draws a line from the current pen location to a specified point. The point must be 
expressed in local coordinates. 


Important 

If a region is open, this command contributes to the region definition; this can 
cause Memory Manager errors to occur. 


Parameters 

Stack before call 


Word —INTEGER; horizontal point to which line will be drawn 
Word —INTEGER; vertical point to which line will be drawn 
<—SP 


previous contents 
h 

V 


Stack after call 


previous contents 


SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void LineTo(h,v) 

Integer h; 

Integer v; 

You can also use the following alternate form of the call- 

extern pascal void LineTo(point) 

Point point; 
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$8404 LocalToGiobal 

Converts a point from local coordinates to global coordinates. Local coordinates are 
based on the current boundary rectangle of the GraflPort. Global coordinates have 
0,0 as the upper left corner of the pixel image. 


Parameters 

Stack before call 
previous contents 

pointPtr — Long—POINTER to point to be converted 

SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void LocalToGiobal(pointPtr) 

Point *pointPtr; 
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$C504 MapPoly 

Maps a specified polygon from a source rectangle to a destination rectangle. 

Parameters 


Stack before call 
previous contents 
— polyHandle 


srcRectPtr 


destRectPtr 


Long—HANDLE to polygon to be mapped 

Long—POINTER to RECr defining source rectangle 

Long—POINTER to RECT defining destination rectangle 
<— SP 


Stack after call 

previous contents | 

|<—SP 

Errors None 

C extern pascal void MapPoly(polyHandle,srcRectPtr,destRectPtr) 

Handle polyHandle; 

Rect *srcRectPtr; 

Rect *destRectPtr; 
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$8A04 MapPt 

Maps a specified p>oint from a source rectangle to a destination rectangle. 

Parameters 


Stack before call 

previous contents 


pointPtr 

— 

srcRectPtr 

— 

destRectPtr 

— 


Long—POINTER to POINT 

Long—POINTER to RECT defining source rectangle 

Long—POINTER to RECT defining destination rectangle 
^SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void MapPt(pointPtr,srcRectPtr,destRectPtr) 

Point *pointPtr; 

Rect *srcRectPtr; 

Rect *destRectPtr; 
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$8B04 MapRect 

Maps a specified rectangle from a source rectangle to a destination rectangle. 

Parameters 


Stack before call 
previous contents 


rectPtr 

— 

srcRectPtr 

— 

destRectPtr 

— 


Long— POINTER to RECT 

Long— POINTER to RECT 

Long— POINTER to RECT 
<— SP 


defining rectangle to be mapped 
defining source rectangle 
defining destination rectangle 


Stack after call 
I previous contents 


SP 


Errors None 

C extern pascal void MapRect(rectPtr,sroReotPtr,destRectPtr) 

Rect *rectPtr; 

Rect *srcRectPtr; 

Rect *destRectPtr; 
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$8C04 MapRgn 

Maps a specified region from a source rectangle to a destination rectangle. 

Parameters 

Stack before call 

Long—HANDLE to region to be mapped 

Long—POINTER to RECT defining source rectangle 

Long—POINTER to RECT defining destination rectangle 

<-SP 


previous contents 


— mapRgnHandle — 


srcRectPtr 


destRectPtr 


Stack after call 


previous contents 


«-SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void MapRgn(mapRgnHandle,srcRectPtr,destdRectPtr) 

RgnHandle mapRgnHandle; 

Rect *srcRectPtr/ 

Rect *destdRectPtr; 
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$3B04 Move 

Moves the current pen location by specified horizontal and vertical displacements. 

Parameters 

Stack before call 
previous contents 


Word—INTEGER; horizontal displacement 
Word—INTEGER; vertical displacement 
«-SP 


Stack after call 

I previous contents I 

14-SP 

Errors None 

C extern pascal void Move(dH,dV) 

Integer dH; 

Integer dV; 
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$2204 MovePortTo 

Changes the location of the current GrafPort’s port rectangle. This routine does not 
affect the pixel image but changes the active area of the GrafPort. The call is normally 
used by the Window Manager. 


Parameters 

stack before call 


Word—INTEGER; horizontai coordinate of upper left corner 
Word—INTEGER; vertical coordinate of upper left corner 
<—SP 


previous contents 
h 

V 


Stack after call 
I previous contents 


<— SP 


Errors None 

C extern pascal void MovePortTo{h,v) 

Integer h; 

Integer v; 
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$3A04 


MoveTo 


Moves the current pen location to a specified point. The point is specified in local 
coordinates. 


Parameters 


Stack before call 


previous contents 


Word—INTEGER; 
Word—^INTEGER; 
<—SP 


horizontal point in local coordinates 
vertical point in local coordinates 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void MoveTo(h,v) 

Integer h; 

Integer v; 

You can also use the following alternate form of the call: 
extern pascal void MoveTo(point) 

Point point; 
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$6704 NewRgn 

Allocates space for a new region and initializes it to an empty region. The empty 
region for this purpose is a rectangular region with a bounding box of (0,0,0,0). 


Important 

NewRgn Is the only routine that creates a new region; all other routines work 
with existing regions, 


Parameters 

Stack before call 

previous contents 

— longspace — Long—Space for result 

<—SP 


Stack after call 
previous contents 

— rgnHandle — Long— ^handle to new region 

SP 

Errors Memory Manager errors Returned unchanged 

C extern pascal RgnHandle NewRgn() 
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$5204 NoiEmptyRect 

Indicates whether a specified rectangle is not empty. An empty rectangle has the top 
greater than or equal to the bottom or the left greater than or equal to the right. 

Parameters 


Stack before call 
previous contents 


wordspace 

—- 

rectPtr 

— 


Word—Space for result 
Long—POINTER to RECT defining rectangle 
<—SP 


Stack after call 

previous contents 

notEmptyFlag Word —^boolean-, TRUE if rectangle not empty, FALSE if empty 

<—SP 

Errors None 

C extern pascal Boolean NotEmptyRect(rectPtr) 

Rect *rectPtr; 


$9204 ObscureCursor 

Hides the cursor until the mouse moves. This routine can get the cursor out of the way 
of typing. 

Parameters The stack is not affected by this call. There are no input or output parameters. 

Errors None 

C extern pascal void ObscureCursor() 
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$C404 OffsetPoly 

Offsets a specified polygon by specified horizontal and vertical displacements. 

Parameters 

Stack before call 

previous contents 
— polyHandle 
~dH 


Long—HANDLE to polygon 

Word—INTEGER; horizontal displacement in pixels 
Word—INTEGER; vertical displacement in pixels 
<—SP 


Stack after call 


previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void OffsetPoly(polyHandle,dH,dV) 

Handle polyHandle; 

Integer dH; 

Integer dV; 
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$4B04 OffsetRect 

Offsets a specified rectangle by specified displacements. The value of dH is added to 
the left and right; the value of dVis added to the top and bottom. 

Parameters 

Stack before call 
previous contents 
rectPtr 


Long—POINTER to rectangle 

Word—INTEGER; horizontal displacement in pixels 
Word—INTEGER; vertical displacement in pixels 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void OffsetRect(rectPtr,dH,dV) 

Rect *rectPtr; 

Integer dH; 

Integer dV; 
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$6F04 OffsetRgn 

Moves a region on the coordinate plane a distance of oW horizontally and dV 
vertically. The region retains its size and shape. 

Parameters 

Stack before call 


Long—^HANDLE to region being offset 

Word—INTEGER; horizontal displacement in pixels 
Word—INTEGER; vertical displacement in pixels 
SP 


previous contents 
rgnHandle 
'dH 

Iv 


Stack after call 


previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 


C 


extern pascal void OffsetRgn(rgnHandle,dH,dV) 

RgnHandle 

rgnHandle; 

Integer 

dH; 

Integer 

dV; 
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$0104 OpenPoly 

Returns a handle to a polygon data stmcture that will be updated by future LineTo 
calls. 

The polygon is completed by making a ClosePoly call. 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

<—SP 


Stack after call 


previous contents 


— polyHandle 


Long—HANDLE to polygon 
SP 


Errors 


$0440 polyAlreadyOpen 
Memory Manager errors 


Polygon already open and being saved in current 
GrafPort 

Returned unchanged 


C 


extern pascal 


Handle OpenPoly() 
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$1804 OpenPort 

Initializes specified memory locations as a standard GrafPort, allocates a new visible 
region and a new clipping region, and makes the GrafPort the current port. 

Parameters 

Stack before call 
previous contents 

portPtr — Long—POINTER to space for GrafPort record 

<— SP 


Stack after call 

previous contents I 

|<—SP 

Errors Memory Manager errors Returned unchanged 

C extern pascal void OpenPort(portPtr) 

GrafPortPtr portPtr; 


$6D04 OpenRgn 

Allocates temporary space and starts saving lines and framed shapes for later 
processing as a region definition. The routine takes no inputs; instead, it allocates 
memory to hold information about the region being created. When the CloseRgn 
routine is called, the region is created and this memory is freed. 

While the region is open, all calls to Line, LineTo, FrameRect, FrameOval, 
FrameRRect, FrameRgn, and FramePoly contribute to the region definition. 

Parameters The stack is not affected by this call. There are no input or output parameters. 


Errors 


C 


$0430 rgnAlreadyOpen Region already being saved in current GrafPort 
Memory Manager errors Returned unchanged 

extern pascal void OpenRgn() 


QuickDraw II routines 16-187 












$6304 PaintArc 

Paints the interior of a specified arc using the current pen mode and pen pattern. 

Parameters 

Stack before call 

previous contents 

rectPtr 

startAngle 
arcAngle 


Long—POINTER to RECT defining enclosing rectangle 

Word—INTEGER; Starting angle in degrees 
Word—INTEGER; arc angle in degrees 
<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void PaintArc(rectPtr,startAngle,arcAngle) 

Rect- *rectPtr; 

Integer startAngle; 

Integer arcAngle; 
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$5904 


PaintOval 

Paints the interior of a specified oval using the current pen mode and pen pattern. 


Parameters 

Stack before call 
previous contents 

rectPtr — Long—POINTER to RECT defining enclosing rectangle 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void PaintOval(rectPtr) 

Rect *rectPtr; 
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$7F04 PaintPixel$ 

Transfers a region of pixels. The pixels are transferred without referencing the current 
GrafPort. The source and destination are defined in the input, as is the clipping 
region. 


Parameters 

Stack before call 
previous contents 

— paintParamPtr — Long—POINTER to parameter block (see Figure 16-35) 

<—SP 


Stack after call 


previous contents 


^SP 


Errors $0420 notEqualChunkiness Source and destination pixel images not the 

same type (one is for 320 mode display and 
one for 640 mode display) 

C extern pascal void PaintPixels(paintParamPtr) 

PaintParamPtr paintParamPtr; 
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Parameter block 

The parameter block pointed to by paintParamPtris shown in Figure 16-35. 

Offset Field 

$0 
1 
2 

3 

4 

5 

6 

7 

8 
9 
A 
B 
C 
D 
E 
F 

10 
11 
12 

13 

14 

15 


Figure 16-35 

PaIntPIxels parameter block 


— pfrToSourceLocInfo — 


— ptrToDestLocInfo — 


ptrToSourceRect — 


— mode — Word— mode 


Long— POINTER to source location Information 


Long— POINTER to destination location Information 


Long— POINTER to source rectangle 


— ptrToDestPoint — Long— POINTER to destination point 


— maskHandie — Long— HANDLE to CllpRgn 
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$BD04 PaintPoly 

Paints the interior of a specified polygon using the current pen mode and pen 
pattern. 


Important 

Because this call allocates and deallocates some temporary memory space. 
Memory Manager errors can occur, 


Parameters 


Stack before call 


previous contents 


polyHandle 


Long—HANDLE to polygon 


<— SP 


Stack alter call 


previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void PaintPoly(polyHandle) 

Handle polyHandle; 
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$5404 PaintRect 

Paints the interior of a specified rectangle using the current pen mode and pen 
pattern. 

Parameters 

Stack before call 
previous contents 

rectPtr — Long —POINTER to RECT defining enclosing rectangle 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void PaintRect(rectPtr) 

Rect *rectPtr; 
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$7A04 PaintRgn 

Paints the interior of a specified region using the current pen mode and pen pattern. 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long—HANDLE to region 
SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void PaintRgn(rgnHandle) 

RgnHandle rgnHandle; 
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$5E04 PaintRRect 

Paints the interior of a specified round rectangle using the current pen mode and pen 
pattern. 

The corners of the round rectangle are sections of an oval defined by ovalHeight and 
ovalWidth. For more information, see Figure 16-12 in the section “Rectangles” in 
this chapter. 


Parameters 


Stack before call 


previous contents 
rectPtr 


ovalWidth 

ovalHeight 


Long—POINTER to RECT defining enclosing rectangle 


Word—INTEGER; width, in pixels, of oval defining rounded corners 
Word—INTEGER; height, in pixels, of oval defining rounded comers 
SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void PaintRRect(rectPtr,ovalWidth,ovalHeight) 

Rect *rectPtr/ 

Word ovalWidth; 

Word ovalHeight; 
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$3604 PenNormal 

Sets the pen state to the standard state, as shown in Table l6-8. Pen location and 
visibility are not changed. 

Parameters The stack is not afTected by this call. There are no input or output parameters. 
Errors None 

C extern pascal void PenNormal() 


Standard pen state table 

Table 16-8 
Standard pen state 


Pen state 

Standard 

PenSize 

1.1 

PenMode 

Copy 

PenPat 

Black 

PenMask 

I’s 
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$D604 PPToPort 

Transfers pixels from a source pixel map to the current port and dips the pixels to the 
current visible region and clipping region. The routine differs from PaintPixels in 
that the current GrafPort is used as the destination. 

PPToPort can help you do the dipping correctly when you are painting a pixel image 
to a window. 

Parameters 

Stack before call 
previous contents 
srcLocPtr 

srcRectPtr 

destX 
destY 

transferMode 


Long—POINTER to source Lodnfo record 

Long—POINTER to RECT defining source rectangle 

Word—INTEGER; X coordinate of upper left corner of destination 
Word—^INTEGER; Y Coordinate of upper left corner of destination 
Word—Same as pen mode (see Table l6-9 in “SetPenMode”) 

SP 


Stack after call 


previous contents 


SP 


Errors $0420 notEqualChunkiness Source and destination pixel images not the 

same type (one is for 320 mode display and 
one for 640 mode display) 

C extern pascal void PPToPort(srcLocPtr,srcRectPtr,destX,destY,transferMode) 

LocInfoPtr srcLocPtr; 

Rect *srcRectPtr; 

Integer destX; 

Integer destY; 

Word transferMode; 
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You can also use the following alternate form of the call: 

extern pascal void PPToPort(srcLocPtr,srcRectPtr,dest,transferMode) 
LocInfoPtr srcLocPtr; 

Rect ’^fsrcRectPtr; 

Point dest; 

Word transferMode; 
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$5004 Pt2Rect 

Copies a specified point to the upper left corner of a specified rectangle and another 
point to the lower right corner of the rectangle. 

Parameters 


Stack before call 

previous contents 


pointlPtr 

— 

point2Ptr 

— 

rectPtr 

— 


Long—POINTER to first source POINT 

Long—POINTER to second source POINT 

Long—POINTER to destination rectangle 
<—SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void Pt2Rect(pointlPtr,point2Ptr,rectPtr) 

Point *pointlPtr; 

Point *point2Ptr; 

Rect *rectPtr; 
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$4F04 PtInRect 

Detects whether the pixel below and to the right of a specified point is in a specified 
rectangle. The routine returns TRUE if the pixel is within the rectangle and FALSE if it 
is not. For example, PtInRect((10,10)),((10,10,20,20)) is TRUE, but 
PtInRect((20,20)),((10,10,20,20)) is FALSE. 


Parameters 


Stack before call 

Word—Space for result 
Long—POINTER to POINT 

Long—POINTER to RECT defining rectangle 
«-SP 


previous contents 


tvordspace 

pointPtr 

— 

rectPtr 

— 


Stack after call 

previous contents 
pointFlag 


Word—BOOLEAN; TRUE if pixel in rectangle, FALSE if not 

<—SP 


Errors None 

C extern pascal Boolean PtInRect(pointPtr,rectPtr) 

Point *pointPtr; 

Rect *rectPtr; 
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$7504 PtInRgn 

Checks to see whether the pixel below and to the right of a specified point is within a 
specified region. The routine returns TRUE if the pixel is within the region and FALSE 
if it is not. 


Parameters 

Stack before call 

Word—^Space for result 
Long—POINTER to POINT 

Long—HANDLE to region 
SP 


previous contents 
wordspace 

pointPtr 


rgnHandle 


Stack after call 
previous contents 

pixelFlag Word—^BOOLEAN; TRUE if pixel is within region, FALSE if not 

<— SP 

Errors Memory Manager errors Returned unchanged 

C extern pascal Boolean PtInRgn(pointPtr,rgnHandle) 

Point *pointPtr; 

RgnHandle rgnHandle; 
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$8604 Random 

Returns a pseudorandom number in the range -32768 to i2l6l. The sequence of 
numbers generated by repeated calls to this routine depends on the randomSeed 
value set by a SetRandSeed call. In particular, a call to SetRandSeed with a given 
randoinSeedyz\\JiQ, followed by a sequence of calls to Random (with no SetRandSeed 
calls in between), will always produce the same sequence of pseudorandom numbers. 
This can be useful in debugging. 


Parameters 

Stack before call 
previous contents 

wordspace Word—Space for result 

SP 


Stack after call 
previous contents 

randomint Word—INTEGER; pseudorandom number 

<— SP 

Errors None 

C extern pascal Integer Random() 
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$7604 RectInRgn 

Checks whether a specified rectangle intersects a specified region. 

Parameters 


Stack before call 
previous contents 


wordspace 

rectPtr 

— 

rgnHandle 

— 


Word—Space for result 

Long—POINTER to RECT defining rectangle 

Long—HANDLE to region 
<—SP 


Stack after call 
previous contents 

encloseFlag Word—BOOLEAN; TRUE if intersection encloses at least a pixel, 

SP FALSE if not 

Errors Memory Manager errors Returned unchanged 

C extern pascal Boolean RectInRgn(rectPtr,rgnHandle) 

Rect *rectPtr/ 

RgnHandle rgnHandle; 
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$6004 RectRgn 

Destroys previous region information by setting a specified region to a specified 
rectangle. If the input does not describe a valid rectangle, the region is set to an 
empty region. If the original region was not rectangular, the region is resized. 


Parameters 


Stack before call 


previous contents 


rgnHandle 

— 

rectPtr 

— 


Long —HANDLE to region being set 

Long —POINTER to RECT defining rectangle used as source 

SP 


Stack after call 


previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void RectRgn(rgnHandle,rectPtr) 

RgnHandle rgnHandle; 

Rect *rectPtr; 
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$CE04 RestoreBufDims 

Restores QuickDraw II’s internal buffers to the sizes described in the eight-byte record 
created by the SaveBufDims routine. You can use this routine when you want your 
application to change temporarily (but be able to restore) the size of the QuickDraw Et 
buffers. 


Parameters 

Stack before call 
previous contents 

— sizeInfoPtr — Long—POINTER to record to be restored 

SP 


Stack after call 
previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void RestoreBufDims(sizeInfoPtr) 

BufDimRecPtr sizeInfoPtr; 
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$CD04 SaveBufDims 

Saves QuickDraw n’s buffer-sizing information in an eight-byte record. You can use 
this routine when you want your application to change temporarily (but be able to 
restore) the size of the QuickDraw II buffers. The buffer-sizing record is shown in 
Figure 16-36. 

Parameters 

Stack before call 
previous contents 

sizeInfoPtr — Long—POINTER to space for record (see Figure 16-36) 

<—SP 


Stack after call 

previous contents I 

|<— SP 

Errors None 

C extern pascal void SaveBufDims(sizeInfoPtr) 

BufDimRecPtr sizeInfoPtr; 


Buffer-Sizing record 

The eight-byte record created by SaveBufDims is shown in Figure 16-36. 


Offset Field 

Word— Application-defined maximum pixel image width 
Word— Current text buffer height. In pixels 
Word— Current text buffer width. In words 

Word— Equal to maxFBR Extent 

Figure 16-36 

BufDImRec 


$0 

1 

2 

3 

4 

5 

6 
7 


— maxWidth 


— textBufHelght — 


textBufferWords 


fonIWIdth 
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$8904 ScalePt 

Scales a specified point from a source rectangle to a destination rectangle. 

Parameters 


Stack before call 

previous contents 


pointPtr 

— 

srcRectPtr 

— 

destRectPtr 

— 


Long—POINTER to POINT to be scaled 

Long—POINTER to RECT defining source rectangle 

Long—POINTER to RECT defining destination rectangle 
<—SP 


Stack after call 


previous contents 


<-SP 


Errors None 

C extern pascal void ScalePt(pointPtr,srcRectPtr,destRectPtr) 

Point *pointPtr; 

Rect *srcRectPtr/ 

Rect *destRectPtr/ 
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$7E04 ScrollRect 

Shifts the pixels inside the intersection of a specified rectangle, visible region, 
clipping region, port rectangle, and bounds rectangle. No other pixels are affected. 
The pixels are shifted a distance of dH horizontally and dV vertically (those shifted 
out of the scroll area are lost). Positive directions are to the right and down. The 
background pattern fills the space created by the scroll. In addition, the region for 
tipdateRgnHandle is changed to the area filled with the background pattern. 

❖ Note: The update region must be an existing region-, ScrollRect does not create it. 
If you do not want the update region, you may pass NIL. 


Parameters 


Stack before call 
previous contents 


rectPtr 


dH 


dV 


—updateRgnHandle — 


Long—POINTER to RECT defining rectangle 

Word—INTEGER; horizontal distance to scroll in pixels 
Word—INTEGER; vertical distance to scroll in pixels 

Long—HANDLE to region 

<—SP 


Stack after call 
previous contents 


Errors 

C 


<—SP 


Memory Manager errors 


Returned unchanged 


extern pascal void ScrollRect(rectPtr,dH,dV,updateRgnHandle) 
Rect *rectPtr; 

Integer dH; 

Integer dV; 

RgnHandle UpdateRgnHandle; 
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$4D04 SectRect 

Calculates the intersection of two rectangles and places the intersection in a 
destination rectangle. The destination rectangle can be one of the source rectangles. 
If the result is not empty, the output is TRUE; if the result is empty, the output is 
FALSE. 


Parameters 


Stack before call 

previous contents 


wordspace 


rectlPtr 


rect2Ptr 


intersectRectPtr 


Word—Space for result 

Long—POINTER to RECT defining first source rectangle 

Long—POINTER to RECT defining second source rectangle 

Long—POINTER to RECT defining destination rectangle 
<— SP 


Stack after call 
previous contents 

notEmptyPlag Word— boolean; TRUE if rectangle not empty, FALSE if empty 

SP 

Errors None 

C extern pascal Boolean SectRect(rectlPtr,rect2Ptr,intersectRectPtr) 

Rect *rectlPtr; 

Rect *rect2Ptr; 

Rect *intersectRectPtr; 
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$7104 SecIRgn 

Calculates the intersection of two regions and places the intersection in a destination 
region. The destination region, which may be one of the source regions, must 
already exist; SectRgn does not allocate it. 

If the regions do not intersect, or if one of the regions is empty, the destination is set 
to the empty region. 


Parameters 


Stack before call 

previous contents 


rgnlHandle 


rgn2Handle 


— destRgnHandle — 


Long—^HANDLE to one source region 

Long—HANDLE to another source region 

Long—HANDLE to destination region 
<—SP 


Stack after call 
previous contents 


Errors 

C 


<— SP 


Memory Manager errors 


Returned unchanged 


extern pascal void SectRgn(rgnlHandle,rgn2Handle,destRgnHandle) 
RgnHandle rgnlHandle; 

RgnHandle rgn2Handle; 

RgnHandle destRgnHandle; 
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$1404 SetAIISCBs 

Sets all SCBs (scan line control bytes) to a specified value. 

Parameters 

Stack before call 
previous contents 

newSCB Word—^New value for SCBs 

SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void SetAIISCBs(newSCB) 

Word newSCB; 
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$B004 Set Arc Rot 

Sets the arcRot field in the GrafPort to a specified value. 

Parameters 


Stack before call 

previous contents 
arcRotValue 


Word—INTEGER; new value of arcRot field 
<— SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void SetArcRot(arcRotValue) 

Integer arcRotValue; 
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$A204 SetBackColor 

Sets the bgColor (background color) field in the GrafPort to a specified value. 
Background color has either a two- or a four-bit value, depending on the port SCB. If 
the port SCB indicates 320 mode, the lower four bits of backColorAie used. If the 
port SCB indicates 640 mode, the lower two bits of backCohrzie used. 


Parameters 

Stack before call 

previous contents 

backColor Word —INTEGER; background color 

SP 


Stack after call 
I previous contents 


SP 


\ 


Errors None 

C extern pascal void SetBackColor(backColor) 

Word backColor; 
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$3404 SetBackPat 

Sets the background pattern to a specified pattern. 

Parameters 

Stack before call 
previous contents 

pattemPtr — Long —POINTER to pattern 

<—SP 


Stack after call 
I previous contents 


SP 


Errors None 

C extern pascal void SetBackPat(patternPtr) 

Pattern patternPtr; 


16-214 QuickDraw 


routines 











$CB04 SetBufDims 

Sets the size of the QuickDraw II dipping and text buffers. This routine overrides the 
maxWidth value supplied to QDStartUp and the text buffer defaults set at that time. 

❖ Note: You only need to make this call if your application is going to use, or allow 
the user to choose, fonts that have unusually large values of cbExtra and spExtra. 

SetBufDims pads the text buffer to permit values of chExtra ^ JbrExtent (of the 
currently active font), spExtra ^ JbrExtent, and style modifications that add up to 36 
pbcels to the bounds width (wid^ of foreground and background) of any character. 

When QDStartUp is called, it makes an internal call to SetBufDims with the following 
values: 

maxWidth As supplied by the application 

maxFontHeight 2 * (height of system font) 
maxFBRExtent 2 * (JbrExtent of system fonO 

Parameters 


Stack before call 


previous contents 
maxWidth 
maxFontHeight 
maxFBRExtent 


Word— INTEGER; width, in bytes, of widest pixel image to be used 
Word— INTEGER; height, in pixels, of tallest font application will use 
Word— INTEGER; greatest JbrExtent, in pixels, of any font to be used 
^SP 


Stack after call 


previous contents 


<r- SP 


Errors Memory Manager errors Returned unchanged 


C 


extern pascal void SetBufDims(maxWidth,maxFontHeight,maxFBRExtent) 

Word maxWidth; 

Word maxFontHeight; 

Word maxFBRExtent; 

(continued) 
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More about parameters 

The maxWidth parameter is the width, In bytes, of the widest pixel image the 
application will draw into. The tnaxFontHeight parameter is the height of the tallest 
font the application will use (that is, fRectHeight from the font record, computable as 
ascent plus descent from the GetFontInfo call). 

The maxFBRExtent parameter is the greatest JbrExtent value of any font the 
application will use. A field in the font record, JbrExtent is returned by a GetFontLore 
or GetFontGlobals caU. It is defined as the greatest (horizontal) distance, in pixels, 
from the character origin to the farthest foreground or background pixel of any 
character in the font For more information, see the section “Fonts and Text in 
QuickDraw H" in this chapter. 
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$D404 SetCharExtra 

Sets the chExtra field in the GrafPort to the specified value. The chExtra field is used 
to add width to every charaaer in the font that has width. It does not affect 0 width 
characters. This field is present because some fonts that look fine in one graphics 
mode need a little extra space between characters in another mode. 

If you set a very large value of chExtra, you may have to change the size of the 
QuickDraw II buffer. See the sections “SetBufDims” and “ForceBufDims” in this 
chapter. 


Important 

SetCharExtra uses FIXED values. You can use the Integer Math Tool Set routine 
FixRatio to convert values to FIXED values. 


Parameters 

Stack before call 
previous contents 

charExtra — Long—FIXED; value for chExtra field 

<—SP 


Stack after call 

previous contents I 

1<—SP 

Errors None 

C extern pascal void SetCharExtra(charExtra) 

Fixed charExtra; 
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$2404 SetClip 

Copies a specified region into the dipping region. The handle to the dipping region 
is not changed. 

Parameters 

Stack before call 
previous contents 

rgnHandle — Long— HANDLE to region 

<—SP 


Stack after call 
previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void SetClip(rgnHandle) 

RgnHandle rgnHandle; 
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$0604 SetCiipHandle 


Sets the cHpRgn handle field in the GraflPort to a specified value. 


Parameters 


Stack before call 

previous contents 


rgnHandle 


Long —HANDLE to clipping region 
<—SP 


Stack after call 
previous contents 


<—SP 


Errors 

C 


None 


extern pascal void SetCiipHandle(rgnHandle) 
RgnHandle rgnHandle; 
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$1004 SetColorEntry 

Sets the value of a color in a specified color table. 

Parameters 


Stack before call 


previous contents 
tableNumber 
entryNumber 
newColor 


Word —INTEGER; number of color table 
Word —INTEGER; number of color to be changed 
Word —INTEGER; master color value for color 

SP 


Stack after call 


previous contents 


SP 


Errors 


C 


$0450 badTableNum Invalid table number; 0 to 15 are valid 

$0451 badColorNum Invalid color number; 0 to 15 are valid 

extern pascal void SetColorEntry(tableNumber,entryNumber,newColor) 
Word tableNumber; 

Word entryNumber; 

ColorValue newColor; 
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$0E04 SetColorTable 

Sets a specified color table to specified values. The l6 color tables are stored starting 
at $9E00. Each table takes $20 bytes. Each word in the table represents one of 4,096 
colors. The high-order nibble of the high-order byte is ignored. 


Parameters 


Stack before call 

previous contents 
tableNumber 


srcTablePtr 


Word —INTEGER; number of table whose color values will be set 
Long —POINTER to color table 

<—SP 


Stack after call 

previous contents I 

|<—SP 

Errors $0450 badTableNum Invalid table number; 0 to 15 are valid 

C extern pascal void SetColorTable(tableNumber,srcTablePtr) 

Word tableNumber; 

ColorTable srcTablePtr; 
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$dE04 SetCursor 

Sets the cursor to an image passed in a specified cursor record. If the cursor is 
hidden, it remains hidden and appears in the new form when it becomes visible 
again. If the cursor is visible, it appears in the new form immediately. See the section 
“Cursors” in this chapter. 


Parameters 

Stack before call 

previous contents 

cursorPtr — Long—POINTER to cursor record 

4—SP 


Stack after call 


previous contents 


4—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void SetCursor(cursorPtr) 

Pointer cursorPtr; 
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$6A04 SetEmptyRgn 

Destroys previous region information by setting a specified region to an empty 
region. The empty region for this purpose is a rectangular region with a bounding 
box of (0,0,0,0). If the original region was not rectangular, the region is resized. 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long —handle to region being modified 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void SetEmptyRgn(rgnHandle) 

RgnHandle rgnHandle; 
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$9404 SetFont 

Sets the current font to a specified font. The call also zeros out the GrafPort’s JontlD 
field. After the call, you can set the font ID to anything desired by using the 
QuickDraw II routine SetFontID (see the section “SetFontID” in this chapter). 


Important 

Under most circumstances, your application should work with the Font Manager 
to set the font It needs. Use this call only If your application Is handling all font 
manipulation by Itself. 


Parameters 

Stack before call 

previous contents 

— newFontHandle — Long—HANDLE to font 

<—SP 


Stack after call 
I previous contents 


<— SP 


Errors None 


C 


extern pascal void SetFont(newFontHandle) 
FontHndl newFontHandle; 
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$9804 SetFontFlags 

Sets the font flags word to a specified value. The font flags word is used to indicate 
special operations performed on the text At the time of publication, two flags are 
cfeflned. See Figure 16-37 for the available values for those flags. 


Important 

The chExtra and spExtra values, and ctvanges to character width, are applied 
after the character widths are fixed by the fonff/ogis setting. 


Paranneters 


Stack before call 

previous contents 
fontFlags 


Word—INTEGER; font flags (see Figure 16-37) 
4-SP 


Stack after call 

[ previous contents 

U—SP 


Errors None 

C extern pascal void SetFontFlags(fontFlags) 

Word fontFlags; 


(continued) 
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Font flags 

The values available for forUFlags are shown in Figure 16-37. 


15|l4|l3ll2|ll|l0|9l9|7i6|s|4|3| 2| 1 |o 


Reserved; set to 0 


T 


Foreground and background colors treated as a word of pixel values = 1 
Foreground and background colors treated as pixel values = 0 


Proportional font = 00 
Nonproportional spacing = 01 
Numeric spacing = 10 
Invalid value = 11 


Figure 16-37 
Font flags word 


If bits 1-0 are set to 00, the font is considered to be a proportionally spaced font. 

If bits 1-0 are set to 01, the font is considered to be a fixed-width font (rather than a 
proportional font), all characters will be equally spaced, and the width of each 
character will be that of the widMax field in the fontinfo record. 

If bits 1-0 are set to 10, the font is considered to be a fixed-width font, all charaaers 
will be equally spaced, and the width of each character will be equal to the character 
width of the font’s 0 (zero) character. This feature makes it easier to line up columns 
of numbers. Because the width used in numeric spacing is usually less than uHdMax, 
some characters—for instance, W’s and M’s—end up overlapping other characters. 
Consequently, numeric spacing is useful with the characters most commonly used 
with numbers, such as the space character or the period, but is not appropriate for 
general text. 

If bit 2 is set to 0, the foreground and background colors are treated as pixel values; 
that is, either as a two- or four-bit number depending on the GrafPort’s SCB. The 
other bits in the word are ignored. Each foreground pixel is given the value of the 
foreground color value, and each background pixel is given the value of the 
background color value. For example, in 640 mode with a foreground color word of 
0110011001100110 and bit 2 set to 0, each pixel will have a value of 10. 

If bit 2 is set to 1, the foreground and background colors are treated as a word’s worth 
of pixel values. This feature is useful when you are trying to draw text in 640 mode 
using dithered colors. Each foreground pixel in a destination word is given the value 
of the corresponding pixel in the foreground color word. Each background pixel in a 
destination word is given the value of the corresponding pb^el in the background 
color word. For example, in 640 mode with a foreground color word of 
0110011001100110 and bit 2 set to 1, odd-numbered pixels will have a value of 10 and 
even-numbered pixels will have a value of 01. 
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$D004 SetFontlD 

Sets the fontID field in the GrafPort. This routine does not change the current font. 

SetFontID is designed for use by the Font Manager for the benefit of the picture 
routines. The picture routines use the font ID to try to find the font the application 
really wanted to draw with, rather than the one that was available when the picture was 
recorded. 


Parameters 

Stack before call 
previous contents 

fontID — Long—Font ID 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetFontID(fontID) 

FontID fontID; 
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$A004 SetForeColor 

Sets the JgColor (foreground color) field in the GrafPort to a specified value. 
Foreground color has either a two- or four-bit value, depending on the port SCB. If 
the port SCB indicates 320 mode, the lower four bits of foreCoUyr are used. If the port 
SCB indicates 640 mode, the lower two bits of foreColor^te used. 


Parameters 

Stack before call 
previous contents 

foreColor Word—INTEGER; foreground color 

4- SP 


Stack after call 

[ previous contents 

U—SP 


Errors None 

C extern pascal void SetForeColor(foreColor) 

Word foreColor; 
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$4404 SetGrafProcs 

Sets the graJProcs field of the current GrafPort to a specified value. 

Parameters 

Stack before call 
previous contents 

~ grafProcsPtr — Long—POINTER to graJProcs record 

SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetGrafProcs(grafProcsPtr) 

QDProcsPtr grafProcsPtr; 
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$B604 SetIntUse 

Indicates to the cursor drawing code whether the code should use scan line interrupts. 

QuickDraw II normally uses scan line interrupts to draw the cursor without flicker. If an 
application wants to use scan line interrupts for some process of its own, it must tell 
(^idcDiaw II not to use them. 


Parameters 

Stack before call 

previous contents 

useint Word—BOOLEAN; TRUE for cursor to use scan line interrupts, 

<— SP FALSE for cursor to not use scan line interrupts 


Stack after call 

previous contents I 

|<— SP 

Errors None 

C extern pascal void SetIntUse(useint) 

Word useint; 
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$1604 SetMasterSCB 

Sets the master SCB to a specified value. The master SCB is the global mode byte used 
throughout QuickDraw II. It is used by routines such as InitPort to decide what 
standard values should be put into the GrafPorL 


Parameters 
Stack before call 

Word—^Value for master SCB Oow-order byte only; high-order byte = 0) 
<—SP 


previous contents 
masterSCB 


Stack alter call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetMasterSCB(masterSCB) 

Word masterSCB; 
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$2304 SetOrigin 

Adjusts the contents of the port rectangle and the bounds rectangle so the upper left 
corner of the port rectangle is set to the specified point. 

The visible region is also affected, but the clipping region is not. The pen position 
does not change. 


Parameters 

Stack before call 


Word—INTEGER; horizontal coordinate of upper left corner 
Word—INTEGER; vertical coordinate of upper left corner 
<—SP 


previous contents 


h 


Stack after call 
I previous contents 


<—SP 


Errors Memory Manager errors Returned unchanged 

C extern pascal void SetOrigin(h,v) 

Integer h; 

Integer v; 

You can also use the following alternate form of the call: 

extern pascal void SetOrigin(point) 

Point point; 
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$3204 SetPenMask 

Sets the pen mask to a specified mask. 

Parameters 

Stack before call 
previous contents 

maskPtr — Long —pointer to pen mask 
^SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void SetPenMask(maskPtr) 

Mask maskPtr; 
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$2E04 SetPenMode 

Sets the current pen mode to a specified pen mode, as shown in Table l6-9. 

Parameters 

Stack before call 
previous contents 

penMode Word— integer-, new pen mode (see Table l6-9) 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetPenMode(penMode) 

Word penMode; 


Pen modes 

Table l6-9 shows the available pen modes. Each 1 and 0 is the value of a bit in a 
pixel. 

❖ Note: Special text modes are also available. See Table 16-10 in the section 
“SetTextMode” in this chapter for those modes. 
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Tabid 16-9 

Pen modes 


Integer Name Description 


$0000 

$8000 


$0001 

$8001 


$0002 

$8002 


$0003 

$8003 


modeCopy 

notCopy 


modeOR 

notOR 


modeXOR 

notXOR 


Copy source (or not source ) to destination. modeCopy is the typical 
drawing mode. For text, the fully colored text pixels (both foreground and 
background) are copied into the destination. 




Pen 



Pen 

modeCopy 


0 1 

notCopy 


0 1 

Destination 

0 

0 1 

Destination 

0 

1 0 


1 

0 1 


1 

1 0 


Overlay (OR) source (or not source ) and destination. Use modeOR to 
nondestructively overlay new images on top of existing images; use notOR to 
overlay inverted images. For text, the fully colored text pixels (both 
foreground and background) are ORed with the destination. 




Pen 



Pen 

modeOR 


0 1 

notOR 


0 1 

Destination 

0 

0 1 

Destination 

0 

1 0 


1 

1 1 


1 

1 1 


Exclusive or (XOR) pen with destination. Use these modes for cursor drawing 
and rubber-banding. If an image is drawn in XOR mode, the appearance of 
the destination at the image location can be restored by drawing the image 
again in XOR mode. For text, the fully colored text pixels (both foreground 
and background) are XORed with the destination. 




Pen 



Pen 

modeXOR 


0 1 

notXOR 


0 

1 

Destination 

0 

0 1 

Destination 

0 

1 

0 


1 

1 0 


1 

0 

1 


modeBiC Bit Clear (BIC) pen with destination ((NOT pen) AND destination). Use this 

notBic mode to explicitly erase (turn off) pixels, often prior to overlaying another 

image. You can use notBIC to display the intersection of two images. For 
text, the fully colored text pixels (both foreground and background) are 
BICed with the destination. 



Pen 

modeBIC 

0 1 

Destination 0 

0 0 

1 

1 0 



Pen 

notBic 

0 1 

Destination 0 

0 0 

1 

0 1 
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$3004 SetPenPat 

Sets the current pen pattern to a specified pen pattern. 

Parameters 

Stack before call 
previous contents 

pattemPtr — Long —pointer to pattern 

SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void SetPenPat(patternPtr) 

Pattern patternPtr; 
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$2C04 


SetPenSize 

Sets the current pen size to a spedfled pen size. 


Parameters 


Stack before call 


previous contents 
penWtdth 
penHeight 


Word —^INTEGER; width of pen in pixels 
Word —INTEGER; height of pen in pixels 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors 

None 


C 

extern 

pascal void SetPenSize(penWidth,penHeight) 


Word 

penWidth; 


Word 

penHeight; 
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$2A04 SetPenState 

Sets the pen state in the GrafPort to specified values. 

Parameters 
Stack before call 
previous contents 

~ penStatePtr — Long— POINTER to pen state record (see Figure 16-38) 

SP 


Stack after call 


previous contents 


<r- SP 


Errors None 


C 


extern pascal void SetPenState(penStatePtr) 
PenStatePtr penStatePtr; 


Pen state record 

The record pointed to by penStatePtr is formatted as shown in Figure 16-38. 
Offset Field 

Long—POINT specifying pen size 


Word— Pen mode 


32 bytes— Pen pattern 


8 bytes— Pen mask 

Figure 16-38 

Pen state record 


$0 

1 

2 

3 

4 

5 

6 


25 

26 


— psPnSize — 


— psPnMode — 


psPnPat 


psPnMask 


2E 
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$3E04 


SetPicSave 

Sets the picSave field in the GrafPort to a specified value. 


Warning 

This is an internai routine that shouid not be used by appiication programs. 

Parameters 

Stack before call 
previous contents 

— picSaveValue — Long—New value for picSave field 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetPicSave(picSaveValue) 

Longint picSaveValue; 
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$4204 SetPolySave 

Sets the polySave field in the GrafPort to a specified value. 

Warning 

This Is an Internal routine that should not be used by application programs. 

Parameters 

Stack before call 
previous contents 

— polySaveValue — Long—New value for polySave field 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetPolySave(polySaveValue) 

Longint polySaveValue; 
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$1B04 


SetPort 

Makes a specified port the current GrafPorL 


Parameters 

Stack before call 

previous contents 


portPtr — Long— POINTER to port 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 


C 


extern pascal void SetPort(portPtr) 
GrafPortPtr portPtr; 
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$1D04 SetPortLoc 

Sets the current port’s locinfo record to specified location information. 

Parameters 

Stack before call 

previous contents 

locInfoPtr — Long—POINTER to location information 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors 


None 


C 


extern pascal void SetPortLoc(locInfoPtr) 
LocInfoPtr locInfoPtr; 
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$1F04 SetPortRect 

Sets the current GrafPort’s port rectangle to the specified rectangle. 

Parameters 

Stack before call 
previous contents 

rectPtr — Long—POINTER to RECT defining rectangle 

<—SP 


Stack after caU 


previous contents 


<—SP 


Errors None 

C extern pascal void SetPortRect(rectPtr) 

Rect *rectPtr; 
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$2104 SetPortSize 

Changes the size of the current GrafPort’s port rectangle. The routine does not affect 
the pixel image; it just changes the active area of the GrafPort. Normally, the call is 
made only by the Window Manager. 


Parameters 


Stack before call 


previous contents 
portWidth 
portHeight 


Word —INTEGER; width of active area in pixels 
Word —INTEGER; height of active area in pixels 
SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetPortSize(portWidth,portHeight) 

Word portWidth; 

Word port Height; 
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$8204 SetPt 

Sets a point to specified horizontal and vertical values. 

Parameters 

Stack before call 
previous contents 
srcPtPtr 
h 

V 


Long—POINTER to POINT 

Word—INTEGER; horizontal value of point 
Word—INTEGER; vertical value of point 
<— SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetPt(srcPtPtr,h,v) 

Point *srcPtPtr; 

Integer h; 

Integer v; 
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$8704 SetRandSeed 

Sets the seed value for the random number generator. The algorithm uses a 32-bit 
seed to produce a l6-bit random number. See the section “Random” in this chapter. 

Parameters 


Stack before call 
previous contents 


— randomSeed — Long—LONGINT; seed value 

<— SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetRandSeed(randomSeed) 

Longint randomSeed; 
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$4A04 


SetRect 

Sets a specified rectangle to specified values. 


Parameters 


Stack before call 



Long—POINTER to space for RECT defining rectangle to be set 

Word—INTEGER; left X coordinate for rectangle 
Word—INTEGER; top Y coordinate for rectangle 
Word—INTEGER; right X coordinate for rectangle 
Word—INTEGER; bottom Y coordinate for rectangle 
<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 


C extern pascal void SetRect(rectPtr,left,top,right,bottom) 

Rect *rectPtr; 

Integer left; 

Integer top; 

Integer right; 

Integer bottom; 
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$6B04 SetRectRgn 

Destroys previous region information by setting a specified region to a specified 
rectangle. If the inputs do not describe a valid rectangle, the region is set to the 
empty region. If the original region was not rectangular, the region is resized. 


Parameters 


Stack before call 



Long —HANDLE to region being set 

Word —INTEGER; left X coordinate for rectangle 
Word —^INTEGER; top Y coordinate for rectangle 
Word —INTEGER; right X coordinate for rectangle 
Word —^INTEGER; bottom Y coordinate for rectangle 
SP 


Stack after call 


previous contents 


<r- SP 


Errors Memory Manager errors Returned unchanged 


C 


extern pascal void SetRectRgn<rgnHandle,left,top^right,bottom) 

RgnHandle 

rgnHandle/ 

Integer 

left; 

Integer 

top; 

Integer 

right; 

Integer 

bottom; 
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$4004 SetRgnSave 

Sets the rgnSave field in the GrafPoit to a specified value. 

Warning 

This is an Internal routine that should not be used by application programs. 

Parameters 

Stack before call 
previous contents 

— rgnSaveValue — Long— handle; new value of rgnSave field 

SP 


Stack after call 
previous contents 


Errors 

C 


<—SP 


None 

extern pascal void SetRgnSave(rgnSaveValue) 
Handle rgnSaveValue; 
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$1204 SetSCB 

Sets the SCB (scan line control byte) to a specified value. 

Parameters 

Stack before call 

previous contents 
scanLine 
newSCB 


Word—INTEGER; scan line whose SCB is to be set 
Word—INTEGER; new value for SCB 
4- SP 


Stack after call 


previous contents 


4—SP 


Errors $0452 badScanLine Invalid scan line number; 0 to 199 are valid 

C extern pascal void SetSCB(scanLine,newSCB) 

Word scanLine; 

Word newSCB; 
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$3804 SetSoiidBackPat 

Sets the background pattern to a solid pattern using a specified color. Only an 
appropriate number of bits in colorNutn are used. If the port SCB indicates 320 
mode, four bits are tised; if it indicates 640 mode, two bits are used. 


Parameters 

Stack before call 

previous contents 

colorNum Word—^INTEGER; new color value 

<— SP 


Stack after call 
previous contents 


Errors 

C 


<r- SP 

None 

extern pascal void SetSoiidBackPat(colorNum) 
Word colorNum; 
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$3704 SetSolidPenPat 

Sets the pen pattern to a solid pattern using the specified color. Only an appropriate 
number of bits in colorNum are used. If the port SCB indicates 320 mode, four bits 
are used; if it indicates 640 mode, two bits are used. 


Parameters 


Stack before call 


previous contents 
colorNum 


Word—INTEGER; new color value 
SP 


Stack after call 

previous contents I 

|<—SP 

Errors None 

C extern pascal void SetSolidPenPat(colorNum) 

Word colorNum; 
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$9E04 SetSpaceExtra 

Sets the spExtra field in the GrafPort to a specified value. The ^Extra field is used by 
programs that are trying to justify text to a left and right boundary. When the spExtra 
field is nonzero, its value is added to the width of each space printed in a string. 


Important 

SetSpaceExtra uses FIXED values. You can use the Integer Math Tool Set 
routine RxRatIo to convert values to FIXED values. 


Parameters 


Stack before call 
previous contents 


spaceExtra — Long—FIXED; new value for spExtra field 

<—SP 


Stack after call 


previous contents 


4—SP 


Errors None 

C extern pascal void SetSpaceExtra(spaceExtra) 

Fixed SpaceExtra; 


A justifying exampie 

You want to display the words a quick brotvn fox and left- and right-justify them in a 
rectangle that measures 200 pixels across. You measure the string and find it to be 
193 pixels long. The string has 3 spaces between words, so you divide 3 into the 7 
pixels remaining (200 - 193 = 7). Thus, you set spEpctra to 2 1/3 (7 + 3 = 2 1/3). 
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$8D04 SetStdProcs 

Sets up a specified record of pointers for customizing QuickDraw II operations. At the 
time of publication, more details were unavailable. 

Parameters 

Stack before call 

previous contents 

— stdProcRecPtr — Long—POINTER to stdProcs record 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 


C 


extern pascal void SetStdProcs(stdProcRecPtr) 
QDProcsPtr stdProcRecPtr; 
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$4804 SetSysField 

Sets the sysField field in the GrafPort to a specified value. 

Warning 

This Is an internal routine that should not be used by application programs. 

Parameters 

Stack before call 
previous contents 

— sysFieldValue — Long—New value for sysField field 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetSysField(sysFieldValue) 

Longint sysFieldValue; 
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$B204 SetSysFont 

Sets a specified font as the system font The default system font is used unless this call 
is made. A handle to the system font is placed in the foniHandie field of each 
GrafPort when it is opened or initialized. 

Parameters 


Stack before call 

previous contents 
— fontHandle 


Long—HANDLE to font that will be system font 
SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetSysFont(fontHandle) 

FontHndl fontHandle; 
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$9A04 SetTextFace 

Sets the text face to a specified value. Up to 16 operations on the text are possible. 
Each bit in textFace represents a different face, as shown in Figure 16-39. 


Parameters 

Stack before call 

previous contents 

textFace Word —INTEGER; text face (see Figure 16-39) 

SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void SetTextFace(textFace) 

TextStyle textFace; 


(continued) 
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Text face flag 

TTie bit values for the textPace parameter are shown in Figure 16-39. 


Important 

Shadow, outline, and Italic styles are available only If QuickDraw II Auxiliary has 
been loaded and started up. Also, fonts that have a descent value of less than 
2 will not be underlined. 


3ll2itllT0f 9 {8| 7|6l6l 4 | 3 | 2 M | 0 


Reserved; set to 0 


T 


Shadow = 1 -■ 

Outline = 1 —' 
Underline = 1 

Italic = 1 -* 
Bold = 1 


Figure 16-39 

Text face flag 
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$9C04 SetTextMode 

Sets the text mode to a specified value. There are eight text-only modes (four modes 
and their opposites), as shown in Table 16 - 10 . The fastest modes are the modes that 
only transfer the foreground to the destination. The fastest of the foreground modes 
are modeForeOR and modeForeXOR; modeForeBIC is almost as fast, and 
modeForeCOPY is the slowest. 

In addition to the text-only modes, the pen modes apply to text See the section 
“SetPenMode” in this chapter. 


Parameters 

Stack before call 
previous contents 

textMode Word— INTEGER; text mode (see Table 16-10) 

SP 


Stack after call 

previous contents I 

1^ SP 

Errors None 

C extern pascal void SetTextMode(textMode) 

Word textMode; 


(continued) 
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Text modes 

The modes shown in Table 16-10 are used only for text They apply when drawing 
from a one-bit-per-pixel world to a two- or four-bit-per-pixel world. You need this 
routine only when drawing from the font to a destination pixel map. 


Table 16-10 
Text-only modes 


Integer Name Description 


$0004 

$8004 

$0005 

$8005 

$0006 

$8006 

$0007 

$8007 


modeForeCopy 

notForeCOPY 

modeForeOR 

notForeOR 

modeForeXOR 

notForeXOR 

modeForeBIC 

notForeBIC 


Copies only the foreground pixels into the 
destination; background pixels are not altered 

Same as modeForeCopy, except that foreground 
pixels are turned to background pixels and 
background pixels are turned to foreground pixels 
before the operation is performed 

ORs only the foreground pixels into the destination; 
background pixels are not altered 

Same as modeForeOR, except that foreground pixels 
are turned to background pixels and background 
pixels are turned to foreground pixels before the 
operation is performed 

XORs only the foreground pixels into the 
destination; background pixels are not altered 

Same as modeForeXOR, except that foreground 
pixels are turned to background pixels and 
background pixels are turned to foreground pixels 
before the operation is performed 

BICs only the foreground pixels into the destination; 
background pixels are not altered 

Same as modeForeBIC, except that foreground 
pixels are turned to background pixels and 
background pixels are turned to foreground pixels 
before the operation is performed 
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$D204 


SetTextSize 

Sets the txSize field of the GrafPort to a specified value. 


Parameters 

Stack before call 
previous contents 

textSize Word—INTEGER; value for txSize field 

4— SP 


Stack after call 


previous contents 


4—SP 


Errors None 

C extern pascal void SetTextSize(textSize) 

Word textSize; 
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$4604 SetUserField 

Sets the userField field in the GrafPort to a specified value. Your application can 
attach data to a GrafPort by using this field as a pointer to some other data area. 

Parameters 

Stack before call 

previous contents 

— userFieldValue — Long—^New value for userField field 

SP 


Stack after call 

previous contents I 

L sp 


Errors None 

C extern pascal void SetUserField(userFieldValue) 

Longint userFieldValue/ 
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$C804 SetVisHandle 

Sets the visPgn field in the GrafPort to a specified value. 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long—HANDLE to visible region 

<—SP 


Stack after call 

( previous contents I 

U—SP 


Errors None 

C extern pascal void SetVisHandle(rgnHandle) 

RgnHandle rgnHandle; 
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$B404 SetVisRgn 

Copies a specified region into the visible region (but does not change the visRgn field 
of the GrafPort). 

Parameters 

Stack before call 

previous contents 

rgnHandle — Long—HANDLE to region 

SP 


Stack after call 


previous contents 


<r- SP 


Errors None 

C extern pascal void SetVisRgn(rgnHandle) 

RgnHandle rgnHandle; 


$9104 ShowCursor 

Shows the cursor by incrementing the cursor level (if the level is already 0, it is not 
incremented). A cursor level of 0 indicates the cursor is visible; a cursor level of less 
than 0 indicates the cursor is not visible. 

Parameters The stack is not affected by this call. There are no input or output parameters. 

Errors None 

C extern pascal void ShowCursor() 
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$2804 ShowPen 

Increments the pen level, A positive pen level indicates that drawing will occur; a 
negative pen level indicates that drawing will not occur. 

Parameters The stack is not affected by this call. There are no input or output parameters. 

Errors None 

C extern pascal void ShowPen() 


$3904 SolidPattern 

Sets a specified pattern to a solid pattern using a specified color. Only an appropriate 
number of bits in colorNum are used. If the port SCB indicates 320 mode, four bits 
are used; if it indicates 640 mode, two bits are used. 


Parameters 


Stack before call 
previous contents 


colorNum 

— 

patternPtr 



Word—INTEGER; 

Long—POINTER 
<—SP 


new color value 
to pattern 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SolidPattern(colorNum,patternPtr) 

Word colorNum; 

Pattern patternPtr; 
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$AD04 StringBounds 

Puts the string bounds rectangle of a specified Pascal-type string into a specified 
buffer. 

Parameters 


Stack before call 
previous contents 


— 

StringPtr 

— 

— 

resultPtr 

— 


Long —POINTER to Pascal-type string 

Long —POINTER to space for RECT defining rectangle 
<—SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void StringBounds(stringPtr,resultPtr) 

Pointer stringPtr; 

Rect *resultPtr; 
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$A904 StringWidth 

Returns the sum of all the character widths, in pixels (pen displacements), of a 
specified Pascal-type string. This would be the pen displacement if the string were to 
be drawn. 


Parameters 


Stack before call 

previous contents 


wordspace 


StringPtr 

— 


Word—Space for result 
Long—POINTER to Pascal-type string 
<—SP 


Stack after call 
previous contents 

StringWidth Word—INTEGER; width of string in pixels 

<— SP 

Errors None 

C extern pascal Integer StringWidth(stringPtr) 

Pointer stringPtr; 
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$8104 SubPt 

Subtracts the source point from the destination point and leaves the result in the 
destination point For example, a source point of (1,2) and a destination point of 
(10,20) result in a destination point of (9,18). 


Parameters 


Stack before call 
previous contents 


— 

srcPtPtr 

— 

— 

destPtPtr 

— 


Long—POINTER to POINT 

Long—POINTER to POINT used as source and destination 
<—SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void SubPt(srcPtPtr,destPtPtr) 

Point *srcPtPtr; 

Point *destPtPtr; 
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$AF04 TextBounds 

Puts the character bounds rectangle of specified text into a specified buffer. 

Parameters 


Stack before call 

previous contents 


-- 

textPtr 

— 

textLength 

— 

resultPtr 

— 


Long—POINTER to text 
Word—INTEGER; length of text in bytes 
Long—POINTER to space for RECT defining rectangle 
<— SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void TextBounds(textPtr,textLength,resultPtr) 

Pointer textPtr; 

Word textLength; 

Rect *resultPtr; 
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$AB04 TextWidth 

Returns the character width, in pixels (pen displacement), of specified text. 

Parameters 

Stack before call 

previous contents 
wordspace 

textPtr 

textLength 

Stack after call 
previous contents 

textWidth Word—INTEGER; width of text in pixels 

<—SP 


Word—Space for result 

Long—POINTER to text 

Word—INTEGER; length of text in bytes 
<—SP 


Errors None 

C extern pascal Integer TextWidth(textPtr,textLength) 

Pointer textPtr; 

Word textLength; 
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$4E04 UnionRect 

Calculates the smallest rectangle that contains both source rectangles and places the 
result in a destination rectangle. 

Parameters 


Stack before call 



Long—POINTER to first source rectangle 

Long—POINTER to second source rectangle 

Long—POINTER to destination rectangle 
SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void UnionRect(rectlPtr,rect2Ptr,unionRectPtr) 

Rect *rectlPtr; 

Rect *rect2Ptr; 

Rect *unionRectPtr; 
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$7204 UnionRgn 

Calculates the smallest region that contains every point that is in either source region 
and places the result in a destination region. The destination region (which may be 
one of the source regions) must already exist; UnionRgn does not allocate it. 

If both regions are empty, the destination is set to an empty region. 

Parameters 


Stack before call 
previous contents 


rgnlHandle 


rgn2Handle 


— unionRgnHandle — 


Long—HANDLE to one source region 

Long—HANDLE to another source region 

Long—HANDLE to destination region 
<— SP 


Stack after call 
previous contents 


Errors 

C 


<—SP 


Memory Manager errors 


Returned unchanged 


extern pascal void UnionRgn(rgnlHandle,rgn2Handle,unionRgnHandle) 
RgnHandle rgnlHandle; 

RgnHandle rgn2Handle; 

RgnHandle unionRgnHandle; 
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$7404 XorRgn 

Calculates the difference between the union and the intersection of two regions and 
places the result in a destination region. The destination region (which may be one of 
the source regions) must already exist; this routine does not allocate it. 

If the regions are not coincident, the destination is set to an empty region. 

Parameters 

Stack before call 

Long—HANDLE to one source region 

Long—HANDLE to another source region 

Long—HANDLE to destination region 
<—SP 


previous contents 
rgnlHandle 


rgn2Handle 


— xorRgnHandle 


Stack after call 

previous contents 


Errors 

C 


<—SP 


Memory Manager errors 


Returned unchanged 


extern pascal void XorRgn(rgnlHandle,rgn2Handle,xorRgnHandle) 
RgnHandle rgnlHandle; 

RgnHandle rgn2Handle; 

RgnHandle xorRgnHandle; 
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QuickDraw II summary 

This section briefly summarizes the constants, data structures, and tool set error codes 
contained in QuickDraw II. 


Important 

These definitions are provided In the appropriate interface file. 


Table 16-11 

QuickDraw ii constants 


Name Value Description 


Color data 

table320 

$32 

table640 

$32 

GrafPort sizes 

maskSize 

$08 

locSize 

$10 

patsize 

$20 

pnStateSize 

$32 

portSize 

$AA 

Color masks 

blueMask 

$000F 

greenMask 

$00F0 

redMask 

$0F0O 

Font flags 

widMaxSize 

$0001 

zeroSize 

$0002 

Master colors 

black 

$0000 

blue 

$0O0F 

darkGreen320 

$0080 

green320 

$OOEO 

green640 

$00FO 

lightBlue320 

$04DF 

purple320 

$072C 

darkGray320 

$0777 

periwinkleBlue320 

$078F 

brown320 

$0841 

lightGray320 

$0CCC 

red320 

$0D00 


320 color table 
640 color table 

Mask size 
Loc size 
Pattern size 
Pen state size 
Size of GrafPort 

Mask for blue nibble 
Mask for green nibble 
Mask for red nibble 

Nonproportional spacing 
Numeric spacing 

Works in 320 and 640 modes 
Works in 320 and 640 modes 
Works in 320 mode 
Works in 320 mode 
Works in 640 mode 
Works in 320 mode 
Works in 320 mode 
Works in 320 mode 
Works in 320 mode 
Works in 320 mode 
Works in 320 mode 
Works in 320 mode 
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Table 16-11 (continued) 
QuickDraw ii constants 


Name 

Value 

Description 

Master colors 

lilac320 

$0DAF 

Works in 320 mode 

red640 

$0F00 

Works in 640 mode 

orange320 

$0F70 

Works in 320 mode 

flesh320 

$0FA9 

Works in 320 mode 

yellow 

$0FF0 

Works in 320 and 640 modes 

white 

$0FFF 

Works in 320 and 640 modes 

Pen modes 

modeCopy 

$0000 

Copy source to destination 

modeOR 

$0001 

Overlay source and destination 

modeXOR 

$0002 

XOR pen with destination 

itiodeBIC 

$0003 

Bit Clear pen with destination 

notCopy 

$8000 

Copy (not source) to destination 

not OR 

$8001 

Overlay (not source) and destination 

notXOR 

$8002 

XOR (not pen) with destination 

notBIC 

$8003 

Bit Clear (not pen) with destination 

Pen and text modes 

itiodeForeCopy 

$0004 

Copy foreground pixels into destination 

modeForeOR 

$0005 

OR foreground pixels into destination 

modeForeXOR 

$0006 

XOR foreground pixels into destination 

modeForeBIC 

$0007 

BIC foreground pixels into destination 

notForeCOPY 

$8004 

Turn background to foreground, then copy 
foreground pixels into destination 

notForeOR 

$8005 

Turn background to foreground, then OR 
foreground pixels into destination 

notForeXOR 

$8006 

Turn background to foreground, then XOR 
foreground pixels into destination 

notForeBIC 

$8007 

Turn background to foreground, then BIC 
foreground pixels into destination 

Mode for QDStartUp 

mode320 

$00 

320 mode 

mode 640 

$80 

640 mode 

SCB byte masks 

colorTable 

$0F 

Color table number 

scbReserved 

$10 

Reserved for future use 

scbFill 

$20 

Fill mode on 

scbinterrupt 

$40 

Interrupt generated when scan line refreshed 

scbColorMode 

$80 

640 mode on 


(continued) 
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Table 16-11 (continued) 
QuickDraw II constants 


Name 

Value 

Description 

Text styles 

boldMask 

$0001 

Mask for bold bit 

italicMask 

$0002 

Mask for italic bit 

unde r1ineMa s k 

$0004 

Mask for underline bit 

outlineMask 

$0008 

Mask for outline bit 

shadowMaak 

$0010 

Mask for shadow bit 

Table 16-12 

QuickDraw II data structures 


Name 

Offset 

Type Definition 


BufDimRec (buffer sizing record) 



maxWidth 

$0 

Word 

Application-defined maximum pixel image width 

textBufHeight 

$2 

Word 

Current text buffer height in pixels 

textBufferWords 

$4 

Word 

Current width of text buffer in words 

fontWidth 

$6 

Word 

Equal to maxFBRExtent used in call 

Font (font record) 

offseToMF 

$00 

Word 

Offset in number of words to Macintosh font part 

family 

$02 

Word 

Font family number 

style 

$04 

TextStyle 

Style font was designed with 

si 2 e 

$06 

Word 

Point size of font 

version 

$08 

Word 

Version number of font definition 

fbrExtent 

$0A 

Word 

Maximum horizontal distance, in pixels, to far edge 
of any foreground or background pixel of any 
character of font 

FontGiobaisRecord 

fgFontID 

$00 

Word 

Family number 

fgStyle 

$02 

TextStyle 

Style font was designed with 

fgSi 2 e 

$04 

Word 

Point size of font 

fgVersion 

$06 

Word 

Version number of font definition 

fgWidMax 

$08 

Word 

Maximum character width of any character in font 

fgFBRExtent 

$0A 

Word 

Maximum horizontal distance, in pixels, to far edge 
of any foreground or background pixel of any 
character of font 

FontInfoRecord 

ascent 

$00 

Integer 

Number of pixels above base line in font rectangle 

descent 

$02 

Integer 

Number of pixels below base line in font rectangle 

widMax 

$04 

Integer 

Maximum character width of any character in font 

leading 

$06 

Integer 

Recommended number of blank pixel rows between 
descent of one text line and ascent of the next 
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Table 16-12 (continued) 
QuickDraw 11 data structures 


Name Offset Type Definition 


GrafPort 


portinfo 

$00 

Locinfo 

portRect 

$10 

Reel 

clipRgn 

$18 

RgnHandle 

visRgn 

$1C 

RgnHandle 

bkPat 

$20 

Pattern 

pnLoc 

$40 

Point 

pnSize 

$44 

Point 

pnMode 

$48 

Word 

pnPat 

$4A 

Pattern 

pnMask 

$6a 

Mask 

pnVis 

$72 

Word 

fontHandle 

$74 

FontHndl 

fontID 

$78 

FontID 

fontFlags 

$7C 

Word 

txSize 

$7E 

Integer 

txFace 

$80 

TextStyle 

txMode 

$82 

Word 

spExtra 

$84 

Fixed 

chExtra 

$88 

Fixed 

fgColor 

$8C 

Word 

bgColor 

$8E 

Word 

picSave 

$90 

Handle 

rgnSave 

$94 

Handle 

polySave 

$98 

Handle 

grafProcs 

$9C 

QdProcsPtr 

arcRot 

$A0 

Integer 

userField 

$A2 

Longint 

sysField 

$A6 

Longint 

Locinfo 

portSCB 

$00 

Word 

ptrToPixImage 

$02 

Pointer 

width 

$06 

Word 

boundsRect 

$08 

Rect 

PaIntParam (PaintPixels parameter block) 

ptiToSource Locinfo 

$00 

LocInfoPtr 

ptrT oDestLocInfo 

$04 

LocInfoPtr 

ptrToSourceRect 

$08 

RectPtr 

ptrToDestPoint 

$0C 

PointPtr 

mode 

$10 

Word 

maskHandle 

$12 

Handle 


Location information 

Port rectangle 

Handle to clipping region 

Handle to visible region 

Background pattern 

Pen location 

Pen size 

Pen mode 

Pen pattern 

Pen mask 

Pen visiblility 

Handle to font 

Font ID 

Font flags 

Text size 

Text face 

Text mode 

Value of space extra 

Value of char extra 

Foreground color 

Background color 

picSave 

rgnSave 

polySave 

Pointer to GrafProcs record 

arcRot 

userField 

sysField 

SCB byte 

Pointer to pixel image 
Width 

Boundary rectangle 

Pointer to source location information 
Pointer to destination location information 
Pointer to source rectangle 
Pointer to destination point 
Mode 

Handle to clipping region 

(continued) 
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Table 16-12 (continued) 
QuickDraw II data structures 


Name 

Offset 

Type 

Definition 

PenState record 

psPnSize 

$00 

Point 

Pen size 

psPnMode 

$04 

Word 

Pen mode 

psPnPat 

$06 

Pattern 

Pen pattern 

psPnMask 

$26 

Mask 

Pen mask 

ROMFonfRecord 

rfFamNum 

$00 

Word 

Font family number of ROM font 

rfPamStyle 

$02 

Word 

Style of ROM font 

rfSize 

$04 

Word 

Point size of ROM font 

rfFontHandle 

$06 

FontHndl 

Handle to font 

rfNamePtr 

$0A 

Pointer 

Pointer to font name 

rfFBRExtent 

$0E 

Word 

JbrExtent for ROM font 


Note: The actual assembly-language equates have a lowercase letter o in front of all of the names given in this 
table. 


Table 16-13 

QuickDraw II error codes 


Code Name Description 


$0401 

$0402 

$0403 

$0410 

$0411 

$0420 

$0430 

$0431 

$0432 

$0433 

$0440 

$0441 

$0442 

$0450 

$0451 

$0452 

$04FF 


alreadyInitialized 
cannotReset 
notInitialized 
screenReserved 

badRect 

notEqualChunkiness 
rgnA1readyOpen 
rgnNotOpen 
rgnScanOverflow 
rgnFull 

polyAlreadyOpen 

polyNotOpen 

polyTooBig 

badTableNum 

badColorNum 

badScanLine 

notImplemented 


Attempt made to start up QuickDraw II without first shutting it down 
Never used 

Quickdraw II not initialized 

Memory Manager reported that screen memory (bank $E1 from 

$2000 to $9FFI0 is already owned by someone else 

Invalid rectangle specified 

Source and destination pixels not the same type 

Region already being saved in current GrafFort 

No region open in current GrafPort 

Region scan overflow 

Region full 

Polygon already open 
Polygon not open 
Polygon too big 

Invalid table number; 0 to 15 are valid 
Invalid color number; 0 to 15 are valid 
Invalid scan line number; 0 to 199 are valid 
Call not implemented 
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Chapter 17 


QuickDraw II 
Auxiliary 


QuickDraw n Auxiliary adds features that did not appear in QuickDraw II because 
of implementation time or memory space. In particular, QuickDraw II adds the 
capability to deal with pictures and allows applications to outline, shadow, and 
italicize text. 

The picture routines listed in this chapter have QuickDraw II tool set numbers, and 
thus could be considered a part of QuickDraw II. However, those routines are not 
available unless QuickDraw II Auxiliary has been loaded and started up, so they are 
included here. 


A preview of the QuickDraw il Auxiliary routines 

To introduce you to the capabilities of QuickDraw II, all QuickDraw II routines are 
grouped by function and briefly described in Table 16-1. These routines are 
described in detail later in this chapter, where they are separated into housekeeping 
routines (discussed in routine number order) and the rest of the QuickDraw II 
routines (discussed in alphabetical order). 













Table 17-1 

QuickDraw II Auxiliary routines and their functions 


Routine Description 


Housekeeping routines 
QDAuxBootInit 

QDAuxStartup 

QDAuxShutDown 

QDAuxVersion 

QDAuxReset 

QDAuxStatus 


Initializes QuickDraw II Auxiliary; called only by the Tool Locator—^must not be 
called by an application 

Starts up QuickDraw II Auxiliary for use by an application 
Shuts down QuickDraw n Auxiliary when an application quits 
Returns the version number of QuickDraw II Auxiliary 

Resets QuickDraw II Auxiliary; called only when the system is reset—must not be 
called by an application 

Indicates whether QuickDraw n Auxiliary is active 


Auxitiiary routines 
OpenPicture 

PicComment 

ClosePicture 

DrawPicture 

KillPicture 

CopyPixels 

Drawicon 

WaitCursor 


Allocates memory for the recording of drawing commands into a picture 

definition and returns a handle to the picture 

Inserts a specified comment into the currently open picture 

Completes the picture definition process begun by an OpenPicture call 

Takes the drawing commands recorded in the picture definition, maps them from 

the picture frame into a specified destination rectangle, and draws them 

Releases all memory occupied by a specified picture 

Copies a pixel image from one place to another, stretching or compressing it as 
necessary to make the source pixels fit the destination rectangle 
Draws a specified icon in a specified mode at a specified location and clips to the 
current visible and clipping regions 

Changes the cursor to a predefined cursor that looks like a watch 


About pictures 

A picture, as defined by QuickDraw n, is a record of drawing commands. The 
OpenPicture call establishes the picture frame that is used in conjunction with the 
destination rectangle to map objects from one space to another when the picture is 
drawn. 

The mapping occurs as follows: If the picture frame is (0,0,100,100) and the 
destination rectangle is (50,50,60,60), a line recorded from (10,10) to (90,90) would 
appear from (51,51) to (59,59) when the picture is drawn. 

Any text drawn is also scaled by using the picture frame and the destination 
rectangle. Using the previous example, a text size of 60 would appear as 6 when the 
picture is drawn. If the horizontal and vertical coordinates are not scaled by an equal 
amount, the vertical change is used to select the correct size for the font. The actual 
scaling of the font is handled by the Font Manager. 
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One of the most common uses of pictures is for printing. The Print Manager uses 
pictures to record what you want to put on a page, then plays back the picture over 
and over again into a band buffer. The band buffer is then printed. Because of this 
technique, your application only has to record the drawing commands once; the 
print driver can use the resulting picture and deal with the appropriate band buffer. 

Another common use of pictures is to pass data back and forth from one application 
to another. The picture data type is one of two standard types defined by the Scrap 
Manager. 


style modification support 

At the time of publication, QuickDraw II provides ROM support for bold and 
underlined text, while QuickDraw II Auxiliary supports outlined, shadowed, and 
italicized text. Therefore, if your application is using outlined, shadowed, or 
italicized text, or if you are allowing the user to choose such style modifications, you 
must load and start up QuickDraw II Auxiliary. 


QuickDraw II Auxiliary icon record 

An icon is a small graphic object that is usually symbolic of an operation or of a 
larger entity, such as a document The QuickDraw n Auxiliary icon record 
indicates whether the icon is in color or black and white, the size of the icon, the 
height and width of the icon, the icon image, and the mask controlling the 
appearance of the icon, as shown in Figure 17-1. 

❖ Note: At the time of publication, this record had not been included in the APW 
interface file. 


Offset Field 



Word— Bit 16 set to 1 = color Icon 

set to 0 = black and white icon 

Word— INTEGER; number of bytes In icon Image 
Word— INTEGER; height of Icon In pixels 
Word— INTEGER; width of Icon In pixels 


X Bytes— Icon Image; iconSize bytes long, each row of pixels Is 
1 + (Icon width -l)/2 bytes wide 


X Bytes— Icon mask; iconSize bytes long, each row of pixels Is 
1 + (Icon width -l)/2 bytes wide 


Figure 17-1 

QuickDraw II Auxiliary Icon record 

QuickDraw II Auxiliary icon record 
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There is also a displayMode word that controls how the iconMask is applied. When 
the displayMode word is 0, the icon is copied to the destination throu^ the specified 
mask. The displayMode word can also have the values shown in Figure 17-2. 


15 

14 

13 

12 

0 

10 

0 

0 

7 

6|5 


3 

0 

0 

0 


I_1_,_J_ I I_[ L, I ^_> 


Background color to 
apply to white part of 
black-and-white Icons 

Foreground color to 
apply to black part of 
black-and-white icons 

Reserved; set to 0 -* 

offLineBIt 

AND light-gray pattern to Image being copied = 1 

Don't AND Image = 0 

openfconBIt 

Copy light-gray pattern Instead of image = 1 
Don't copy light-gray pattern o 

selectedlconBIt 

Invert Image before copying = 1 
Don't invert Image = 0 


Figure 17-2 

The displayMode word 

All three of the operations in bits 2-0 can occur at once, and the testing is in the 
following order: 

1. Check openIconBit G>it 1). Is it open (set to 1)? 

2. Check offLineBit (bit 2). Is it off-line (set to 1).^ 

3. Check selectedIconBit (bit 0). Is it selected (set to 1)? 

Color is only applied to the black and white icons if bits 15-8 are not all 0. Colored 
pixels in an icon are inverted by black pixels becoming white and any other color of 
pixel becoming black. 

Your application draws the icon by using a Drawicon call. See the section 
“Drawicon” in this chapter. 


17-4 


Chapter 17: QuickDraw II Auxiliary 



Using QuickDraw II Auxiliary 

This section discusses how the QuickDraw II Auxiliary routines fit into the general flow 
of an application and gives you an idea of which routines you’ll need to use under 
normal circumstances. Each routine is described in detail later in this chapter. 

QuickDraw II Auxiliary depends on the presence of the tool sets shown in Table 17-2 
and requires that at least the indicated version of the tool set be present. 


Table 17-2 

QuickDraw II Auxiliary—other tool sets required 


Tool set 
number 

Tool set 
name 

Minimum version 
needed 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$04 

#04 

QuickDraw n 

1.2 


In addition, if your application is using the DrawPicture routine, the Font Manager 
(tool set number $1B) must be loaded and started up. 

The first QuickDraw II Auxiliary call your application must make is QDAuxStartUp. 
Conversely, when you quit your application, you must make the QDAuxShutDown 
call. 

The OpenPicture begins the picture definition process. While OpenPictuie is in 
effect, QuickDraw II drawing commands and any comments from PicComment calls 
are recorded and placed in the picture definition. When your application is through 
recording the picture, use the ClosePicture routine to stop the picture definition 
process and the DrawPicture routine to draw the picture in the destination rectangle. 
Finally, when you are completely through with a picture, you can use the KillPicture 
routine to release the memory the picture occupies. 

Your application can draw an icon by using a Drawicon call, produce a cursor that 
looks like a watch by using a WaitCursor call, or copy a pixel image from one place to 
another by using a CopyPixels call. 
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$0112 


QDAuxBootlnit 

Initializes QuickDraw II Auxiliary; called only by the Tool Locator. 



Warning 

An application must never make this call. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call must not be made by an application. 


$0212 

QDAuxStartUp 

Starts up QuickDraw II Auxiliary for use by an application. 

Important 

Your application must make this call before it makes any other QuickDraw 11 
Auxiliary calls. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void QDAuxStartUp() 
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$0312 QDAuxShutDown 

Shuts down QuickDraw II Auxiliary when an application quits. 


Important 

If your application has started up QuickDraw 11 Auxillaty, the application must 
make this call before it quits. 


Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 


C 


extern pascal void QDAuxShutDown() 


$0412 QDAuxVersion 

Returns the version number of QuickDraw II Auxiliary. 

Parameters 


Stack before call 


previous contents 
wordspace 


Word —Space for result 
<— SP 


Stack after call 
previous contents 

versioninfo Word —^Version number of QuickDraw II Auxiliary 

Errors None 

C extern pascal Word QDAuxVersion{) 
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$0512 QDAuxReset 

Resets QuickDraw II Aujdliary; called only when the system is reset 
Warning 

An application must never make this call. 

Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C Call must not be made by an application. 


$0612 QDAuxStatus 

Indicates whether QuickDraw II Auxiliary is active. 

Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

^SP 


Stack after call 

previous contents 
activeFlag 


Word—^BOOLEAN; TRUE if QuickDraw II Auxiliary active, FALSE if inactive 
<— SP 


Errors None 

C extern pascal Boolean QDAuxStatus() 
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m 



ClosePicture 


Completes the picture definition process begun by an OpenPicture call. 


Important 

Calls to OpenPicture and ClosePicture must be balanced; that Is, one 
ClosePicture call must be made for every OpenPicture call. 


ClosePicture calls the QuickDraw II routine ShowPen, thus balancing the HidePen call 
made by the OpenPicture call. 


Parameters The stack is not affected by this call. There are no input or output parameters. 


Errors 


None 


C 


extern pascal void ClosePicture() 
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$0912 CopyPixels 


Copies a pixel image from one place to another, stretching or compressing it as 
necessary to make the source pixels fit the destination rectangle. 

If the destination locinfo record is the same as the locinfo record of the current 
GrafPort, the pixels are also clipped to the GrafPort’s visible and clipping regions. 


Parameters 

Stack before call 


previous contents 


srcLocPtr 

— 

destLocPtr 

— 

srcRect 

— 

destRect 

— 

xferMode 

maskRgn 

— 


Long—POINTER to locinfo record of source rectangle 

Long—POINTER to locinfo record of destination rectangle 

Long—POINTER to RECT defining source rectangle 

Long—POINTER to RECT defining destination rectangle 
Word—^Pen mode 
Long—^HANDLE to mask region 
<— SP 


Stack after call 


previous contents 


<r- SP 


Errors None 

C extern pascal void CopyPixels(srcLocPtr,destLocPtr,srcRect,destRect, 

xferMode,maskRgn) 

LocInfoPtr srcLocPtr; 

LocInfoPtr destLocPtr; 

Rect *srcRect/ 

Re ct * de st Re ct; 

Word xferMode; 

RgnHandle maskRgn; 
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$0B12 Drawicon 

Draws a specified icon in a specified mode at a specified location and clips to the 
current visible and clipping regions. The routine does not contibute to a picture 
definition, nor does it print the icon. 

The QuickDraw II Auxiliary icon record and display mode word are described in the 
section “QuickDraw II Auxiliary Icon Record” in this chapter. 


Parameters 


Stack before call 


previous contents 


iconPtr 


displayMode 


xPos 


yPos 


Long—POINTER to icon record (see Figure 17-1) 

Word—Bit flag defining icon’s appearance (see Figure 17-2) 
Word—coordinate of upper left corner of icon 
Word —Y coordinate of upper left corner of icon 
SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void Drawicon(iconPtr,displayMode,xPos,yPos) 


Pointer 

iconPtr; 

Word 

displayMode; 

Word 

xPos; 

Word 

yPos; 
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$BA04 DrawPicture 

Takes the drawing commands recorded in the picture definition, maps them from the 
picture frame into a specified rectangle, and draws them. 


Warning 

If you call DrawPicture with the Initial, arbitrarily large clipping region, and the 
destination rectangle Is either offset or larger than the picture frame, the 
clipping region might be set to empty and no drawing will be done. 


DrawPicture passes any picture comments to a low-level procedure accessed through 
the graJProcs field of the GrafPort. For more information, see the section 
“PicComment” in this chapter. 

Parameters 


Stack before call 


previous contents 


picHandle 

— 

destRect 

— 


Long—HANDLE to picture 

Long—POINTER to RECT defining destination rectangle 
<—SP 


Stack after call 
previous contents 

l^sp 

Errors None 

C extern pascal void DrawPicture(picHandle,destRect) 

Handle picHandle; 

Rect *destRect; 
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$BB04 KillPicture 

Releases all memory occupied by a specified picture. Use this call only when your 
application is completely through with a picture. 

Parameters 

Stack before call 

previous contents 

picHandle — Long —HANDLE to picture 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void KillPicture(pichandle) 

Handle pichandle; 
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$B704 OpenPicture 

Allocates memory for the recording of drawing commands into a picture definition, 
and returns a handle to the picture. 


Warning 

A Graf Port's clipping region Is initialized to an arbitrarily large region. To ensure 
that the clipping region is still valid when drawing occurs and the region is 
mapped from the pIcFrame to the destRect you should always change the 
clipping region to a smaller region before calling OpenPicture. 


OpenPicture also calls the QuickDraw II routine HidePen, so no drawing will occur on 
the screen while the picture is open. 

❖ Note: No drawing will occur unless you call ShowPen just after OpenPicture, or you 
call ShowPen without previously balancing it by a call to HidePen. 

When a picture is open, the GrafPort's picSave field contains a handle to information 
related to the picture definition. If you want to temporarily disable the collection of 
routine calls and picture comments, save the current value of picSave and set the field 
to NIL; then restore the value when you want to resume the picture definition. 


Parameters 

Stack before call 


previom contents 


longspace 

— 

picFrame 

— 


Long—Space for result 

Long—POINTER to RECT defining picture frame 
SP 


Stack after call 

previous contents 

picHandle — Long—HANDLE to picture 

<— SP 

Errors None 

C extern pascal Handle OpenPicture(picFrame) 

Pointer picFrame; 
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$B804 PicComment 

Inserts a specified comment into the currently open picture. An application that 
processes the comments must include a procedure to do the processing and store a 
pointer to that procedure in the graJProcs field of the GrafPort. 

❖ Note: The standard low-level procedure for processing picture comments simply 
ignores all comments. 


Parameters 


Stack before call 


previous contents 
commentKind 
dataSize 


Word—^Type of comment 

Word—Size of additional data; 0 if none 


dataHandle 


Long—HANDLE to additional data; NIL if none 


SP 


Stack after call 
previous contents 


^SP 


Errors None 


C extern pascal void PicComment(commentKind,dataSize,dataHandle) 

Integer commentKind; 

Integer dataSize; 

Handle dataHandle; 
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$0A12 

WaitCursor 

Changes the cursor to a predefined cursor that looks like a watch. 

❖ Note: You can restore the standard arrow cursor by making the QuickDraw II call 
InitCursor. 

A desk accessory or tool set can make this without checking whether QuickDraw n 
Auxiliary is active and without checking for errors. If QuickDraw II Auxiliary has not 
been loaded and started up, the dispatcher will return an error, but nothing else will 
happen. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void WaitCursor() 


QuickDraw II Auxiliary summary 

QuickDraw II Auxiliary does not contain any predefined constants, data structures, or 
error codes. 
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Chapter 18 


SANE Tool Set 


The Standard Apple Numeric Environment (SANE) is extended-precision IEEE 
arithmetic, with elementary functions. It scrupulously conforms to the IEEE standard 
754 for binary floating-point arithmetic and to the proposed IEEE standard 854, 
which is a radix-independent and word-length-independent standard for floating¬ 
point arithmetic. 

SANE provides sufficient numeric support for most applications. It includes 

■ IEEE types single G2-bit), double (64-bit), and extended (80-bit) 

■ A 64-bit type for large integer computations, such as those used in accounting 

■ Fundamental floating-point operations ( + - * / V rem) 

■ Comparisons 

■ Binary-decimal and float-integer conversions 

■ Scanning and formatting for ASCII numeric strings 

■ Logs, trigs, and exponentials 

■ Compound and annuity functions for financial computations 

■ A random-number generator 

■ Functions for management of the floating-point environment 

■ Other functions required or recommended by the IEEE standard 

The SANE Tool Set fully supports the Standard Apple Numeric Environment, 
matching the functions of the Macintosh SANE padcages, as well as those of the 6502 
assembly language SANE software from which it is derived. 








The SANE Tool Set comprises the usual tool set housekeeping routines and the 
routines SANEFP 8 I 6 , SANEElenis8l6, and SANEDecStr8l6 that serve as entry points 
for the major pieces of SANE code. Each call to SANEFP 8 I 6 , SANEElems8l6, or 
SANEDecStr8l6 passes an opword parameter specifying the operation to be 
performed. For example, the opword $0206 passed to SANEFP 8 I 6 indicates “divide 
by a value of type single.” 

This chapter describes only the basic functions of the SANE routines and the 
differences between the 65C816 version and the 6502 version. SANE functions are 
completely documented in the Apple Numerics Manual, which you will need if you 
use SANE routines in your application. 


A preview of the SANE Tool Set routines 

To introduce you to the capabilities of the SANE Tool Set, all SANE Tool Set routines 
are grouped by function and briefly described in Table 18-1. These routines are 
desaibed in detail later in this chapter, where they are separated into housekeeping 
routines (discussed in routine number order) and the rest of the SANE Tool Set 
routines (discussed in alphabetical order). 

Table 18-1 

SANE Tool Set routines and their functions 
Routine Description 


Housekeeping routines 


SANEBootInit 

SANEStartup 

SANEShutDown 

SANEVersion 

SANEReset 

SANEStatus 


Initializes the SANE Tool Set; called only by the Tool Locator—must not be called 
by an application 

Starts up the SANE Tool Set for use by an application 
Shuts down the SANE Tool Set when an application quits 
Returns the version number of the SANE Tool Set 

Resets the SANE Tool Set; called only when the system is reset—^must not be called 
by an application 

Indicates whether the SANE tool set is active 


SANE routines 

SANEDecStr8l6 

SANEElems8l6 

SANEFP 8 I 6 


Contains numeric scanners and formatter 

Contains elementary functions, financial functions, and a random-number 
generator 

Contains basic arithmetic operations, comparsions, conversions, environmental 
control, and IEEE auxiliary operations 
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Using the SANE Tool Set 

This section discusses how the SANE Tool Set routines fit into the general flow of an 
application and gives you an idea of which routines you'll need to use under normal 
circumstances. Each routine is described in detail later in this chapter. 

The SANE Tool Set depends upon the presence of the tool sets shown in Table 18-2 
and requires that at least the indicated version of the tool set be present. 

Table 18-2 

SANE Tool Set-other tool sets required 

Tool set Tool set Minimum version 

number name needed 


$01 #01 Tool Locator 1.0 

$02 #02 Memory Manager 1.0 

The first SANE Tool Set call that your application must make is SANEStartUp. 
Conversely, when you quit your application, you must call SANEShutDown. 

You can program with the SANE tool set using any assembler that generates code for 
the Apple IIGS. The equate file SANE.equs and the macro file M16.SANE help you 
use SANE with the Apple IIGS Programmer’s Workshop (APW) assembler. 

❖ Note: The APW C Compiler fully supports SANE and includes C interfaces to all 
SANE tool set routines. 

The following code for a binary operation illustrates a typical invocation of a SANE 
function: 

PUSHLONG <4-byte source operand address> 

PUSHLONG <4-byte destination operand address> 

PUSHWORD <OpWord> 

(SANE macro) 

Some SANE operations require different numbers of arguments, some pass l6-bit 
integer arguments by value, and some return results in the X, Y, and status registers. 

The following example illustrates the use of the numeric scanner and formatter. The 
procedure accepts as an argument an ASCII string representing a number of degrees 
and returns the trigonometric sine of the argument as a numeric ASCII string. Both 
input and output are Pascal strings; that is, byte 0 gives the length, and byte 1 
contains the first character in the string. The caller of the procedure pushes the 
address of the input string and performs a JSR to SINE. The procedure overwrites the 
input string with the result (whose length may be as large as 80) and clears the stack. 
SINE uses SANEFP816, SANEElems8l6, and SANEDecStr8l6, which are the three 
principal functions in the SANE Tool Set. 
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/ Somewhere early in the program, initialize SANE 
; Call the Memory Manager to reserve 256 bytes of bank $0 for use 

; as SANE direct page. iSANEdirectpg is the address of this memory in this example 
PUSHWORD #SANEdirectpg 
_SANEStartUp 

; Near the end of the program, shut down SANE. 

_SANEShutDown 

; Call the Memory Manager to release the memory reserved for the 
; SANE direct page (often by releasing ALL reserved memory) 

; Procedure SINE (var s : DecStr) 


s : 

I/O string 

index : 

16-bit integer index 

theDec : 

Decimal record 

vp : 

Boolean for validprefix 

theForm : 

decform record 

X : 

Extended temporary 

const ; 

Extended constant - pi/180 


SINE 


ENTRY 


PLA 


STA 

return 

PLA 


STA 

sAdr 

PLA 


STA 

sAdr+2 

LDA 

#1 

STA 

index 

PUSHLONG 

sAdr 

PUSHLONG 

#index 

PUSHLONG 

ttheDec 

PUSHLONG 

#vp 

FPSTR2DEC 



; Save return address 


; Address of s -> sAdr 


; 1 -> index 


; s -> theDec 
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PUSHLONG 

#theDec 




PUSHLONG 

#x 




FDEC2X 


! 

theDec -> X 


PUSHLONG 

#const 




PUSHLONG 

#x 




FMULX 


} 

Convert to radians: x*const -> x 


PUSHLONG 

#x 




FSINX 


! 

Sin(x) -> X 


PUSHLONG 

#theForm 




PUSHLONG 

#x 




PUSHLONG 

#theDec 




FX2DEC 


/ 

X -> theDec 


PUSHLONG 

#theForm 




PUSHLONG 

ttheDec 




PUSHLONG 

sAdr 




FDEC2STR 


t 

theDec -> s 


LDA 

return 




PHA 





RTS 




index 

ds 

2 



vp 

ds 

2 



const 

dc 

h'AE C8 E9 94 

12 35 FA 8E F9 3F» ; Constant * pi/180 

X 

ds 

10 



theForm 

dc 


} 

First style, then digits 

theDec 

ds 

33 

r 

Sign, exponent, length, ASCII = (2+2+1+28) 

return 

ds 

2 



sAdr 

ds 

4 
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Performance characteristics and limitations 

Your application must preserve bytes 24 to 29 (decimal) of the SANE direct page 
between calls to SANE, Those 6 bytes hold the floating-point environment and halt 
vector. The remainder of the SANE direct page is scratch space used only during 
SANE execution and does not need to be preserved across calls to SANE. The space 
is thus available to the application. 


Warning 

Future Implementations of SANE on the IIgs may not store the floating-point 
environment and halt vector on the direct page. If you access these variables 
directly, you may forfeit upward compatibility. Always access these variables 
only through SANE calls. 


Except for the SANEVersion routine, SANE Tool Set routines remove all arguments 
from the stack and return no results on the stack. Temporary stack growth during calls 
does not exceed 40 bytes (50 for elementary function calls). 

The SANE Tool Set conforms to the general tool set rules for management of the CPU 
registers, modes, and busy flag. However, SANE never returns tool set error codes; 
all floating-point errors are handled internally by setting exception flags (see the 
Apple Numerics Manual). 


Typical timings, based on a few sample values, are as follows: 


0.5 - 1.2 ms 
1,0 - 5,0 ms 
1.9 - 5.2 ms 
0.7 -1.4 ms 
0.8 - 1.0 ms 
2.4 - 5.8 ms 
0.8 ~ 3.5 ms 
50 -100 ms 


Add, subtract 

Multiply 

Divide 

Scanner 

Formatter 

Extended-to-decimal 
Decimal-to-extended 
Trigonometric, exponential, logarithmic 
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Differences between 650816 and 6502 SANE 

The 65C816 version of SANE differs from the 6502 version in several ways. First, all 
address parameters in the 65C816 are 4 bytes instead of 2 bytes. Another difference 
is that, if you are not using macro calls, you access the routines via the tool set 
dispatcher rather than via a JSR statement. Thus, invocations end with 

LDX #SANEtsNum + FuncNum*256 

JSL $E10000 

instead of 

JSR <xx6502> 

If you are using the macro calls, you don't see this difference, because the macro 
automatically expands into the correct version of the call. 

The low-order bytes of the X and Y registers return information as documented in 
Part II of the Apple Numerics Manual The high-order byte of X duplicates the 
contents of the low-order byte of Y. The high-order byte of Y is undefined. 

Figure 18-1 shows the relationship between the return information in 6502 registers 
and that in 65816 registers. 

/- High-order byte - n 


65C616X 

register 


6502 Y 
register 


6502 X 
register 


^- Low-order byte 

Figure 18-1 

SANE return Information 


65C816Y 

register 


? 


6502 Y 
register 
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The Remainder call uses the N flag from the Processor Status register and both bits 7 
and 15 of the X register to return the sign of the quotient. The low 7 bits of X contain 
the absolute value of the quotient. 

The final difference between the 65816 and 6502 versions lies in the halt mechanism. 
When a halt occurs in 65816 SANE, the input parameters and SANE opcode are 
located in the SANE direct page, as shown in Figure 18-2. For one- and two-argument 
calls, C holds the address of DST. For two-argument calls, B holds the address of 
SRC. For binaryr-to-decimal conversion, A holds the address of the decimal record, 
B holds the address of the binary value, and C holds the address of the decform 
record. 


Important 

Halts occur only on colls to SANEFP816. SANEEIems816 stimulates the halt 
mechanism only through the procexit call. SANEDecStr816 makes no calls to 
SANEFP816 and therefore never stimulates the halt mechanism. 


The halt vector is the address of a halt-handling routine stored as a 4-byte address. 
The SetHaltVector routine expects the 4-byte halt vector to be passed by value on the 
stack. GetHaltVector returns a 3-byte halt vector in the X and Y registers. X contains 
the two low bytes (first and second) of the halt vector, and Y contains the second and 
third bytes; the second byte of the halt vector occurs in both the X and Y registers. 
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$0 

1 

2 

3 

4 

6 

6 

7 

8 

9 

OA 

OB 

OC 

OD 

OE 

OF 

10 

11 

12 

13 

14 

16 

16 

17 

18 

19 

lA 

IB 

1C 

ID 

IE 

IF 

20 

21 

22 


18-2 illustrates how X and Y return the halt vector. 


Field 


2 return addresses 


Caller's direct page 


Caller's data bank 


Opword 


“C* address 


“B" address 


"A" address 


Halt vector 


Environment 


Pending exceptions 

Pending X-lo 

Pending X-hl, Y-lo 
Pending Y-hi 


I 18-2 

direct page on halt 
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When a halt occurs, the 65816 SANE executes a JSL to HaltVector. The halt handler 
can continue execution as if no halt had occurred by executing RTL. 


Important 

SANE Is not reentrantl Your application can't call SANE within the halt handler. 
During the halt, the direct page can't be altered, and making a SANE call would 
alter the direct page. 


After return to the SANEFP 8 I 6 code, SANE uses the A register, not pending 
exceptions, to set the final floating-point exceptions. Execute LDA 
PendingExceptions at the end of the halt handler to ensure that the exceptions from 
the current call are handled correctly. 


Warning 

Pending exceptions is a sum of the five exception constants, represented as an 
Integer from 0 to 31. Unpredictable results occur if the A register contains a 
value outside this range when your application exits the halt handler. 
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$01OA 

SANEBootInit 

Initializes the SANE Tool Set; called only by the Tool Locator. 

Warning 

An application must never make this call. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call must not be made by an application. 


SANE Tool Set housekeeping routines 
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$020A SANEStartUp 

Starts up the SANE Tool Set for use by an application. This routine clears the SANE 
environment word, installing the default settings of round-to-nearest, round-to- 
extended-precision, all exceptions clear, and all halts disabled (these terms are 
defined in the Apple Numerics Manual). 


Important 

If you are using assembly language, your application must make this call before 
making any other SANE calls. If you are using APW C, the call Is made 
automatically. 


SANEStartUp also sets the halt vector to 0. As with 6502 SANE, halts remain 
inoperative until the application both enables halts and also gives the halt vector a 
nonzero address. 

The dPageAddr paxzxoex&t is the address of one page (256 bytes) in bank $0 that your 
application makes available to the SANE Tool Set for its use. 


Parameters 

Stack before call 
previous contents 

dPageAddr Word—Bank $0 starting address of one page of direct-page space 

<—SP 


Stack after call 
previous contents 


<—SP 


Errors None 

C The call is made automatically in APW C. 
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$030A SANEShutDown 

Shuts down the SANE Tool Set. 


Important 

If your application has started up the SANE Tool Set. the application must make 
this call before It quits. 


Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 


C 


extern pascal void SANEShutDown() 


$040A SANEVersion 

Returns the version number of the SANE Tool Set. 

Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

SP 


Stack after call 

previous contents 
versionin/o 


Word—^Version number of SANE Tool Set 
SP 


Errors None 


C 


extern pascal Word SANEVersion() 


SANE Tool Set housekeeping routines 
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$050A SANEReset 

Resets the SANE Tool Set; called only when the system is reset. 


Warning 

An application must never make this call. 


Parameters 

Errors 

C 


The stack is not affected by this call. There are no input or output parameters. 
None 

Call must not be made by an application. 


$060A SANEStatu$ 

Indicates whether the SANE Tool Set is active. 

Parameters 

Stack before call 

previous contents 
wordspace 


Stack after call 
previous contents 

aciiveFlag Word —BOOLEAN; TRUE if SANE Tool Set active, FALSE if inactive 

<—SP 

Errors None 

C extern pascal Boolean SANEStatusO 


Word —Space for result 
<—SP 
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$OAOA SANEDecStr816 

Contains numeric scanners and formatter. 

Parameters See the Apple Numerics Manual for details. 

Errors None 


C 


extern pascal Void SANEDecStr816() 


$0B0A SANEEIems816 

Contains elementary functions, financial functions, and a random-number 
generator. 

Parameters See the Apple Numerics Manual for details. 

Errors None 


C 


extern pascal Void SANEElems816() 


$090A 


Parameters 

Errors 

C 


SANEFPd16 

Contains basic arithmetic operations, comparisons, conversions, environmental 
control, and IEEE auxiliary operations. 

See the Apple Numerics Manual for details. 

None 

extern pascal Void SANEFP816() 


SANE Tool Set summary 

The constants and data structures for the SANE Tool Set are defined in the Apple 
Numerics Manual. The SANE Tool Set does not contain any tool set error codes. 


SANE Tool Set routines 
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Chapter 19 


Scheduler 


The Scheduler delays activation of a desk accessory or of other tasks until the 
resources that the desk accessory or task needs become available. Much of the 
system code is not reentrant; that is, the code cannot be called while it is already 
executing. For example, if a desk accessory was activated while the system was within 
nonreentrant code, the system would most likely fail. To prevent such a situation 
from occurring, the Apple IIGS provides a busy flag that the Scheduler can check to 
see if a needed resource is busy or available. 

If you are writing an application or a desk accessory, you won't need to use the 
Scheduler. The only time you need to use the Scheduler is when you aie writing one 
of the following: 

■ Your own tool set 

■ Interrupt handlers that access ProDOS l6 or the tool set routines 

For example, an application that performed background printing might need to 
access the Scheduler. 


A preview of the Scheduler routines 

To introduce you to the capabilities of the Scheduler, all Scheduler routines are 
grouped by function and briefly described in Table 19-1* These routines are 
described in detail later in this chapter, where they are separated into housekeeping 
routines (discussed in routine number order) and the rest of the Scheduler routines 
(discussed in alphabetical order). 
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Table 19-1 

Scheduler routines and their functions 


Routine Description 


Housekeeping routines 

SchBootInit Initializes the Scheduler; called only by the Tool Locator—must not be called by an 
application 

SchStartUp Starts up the Scheduler for use by an application 

SchShutDown Shuts down the Scheduler when an application quits 
SchVersion Returns the version number of the Scheduler 

SchReset Resets the Scheduler; called only when the system is reset—must not be called by an 

application 

SchStatus Indicates whether the Scheduler is active 

Scheduler queue routines 

SchAddTask Adds a task to the Scheduler queue 

SchFlush Flushes all tasks in the Scheduler queue—^must not be called by an application 


Using the Scheduler 

This section discusses how the Scheduler routines fit into the general flow of an 
application and gives you an idea of which routines youll need to use under normal 
circumstances. Each routine is described in detail later in this chapter. 

The Scheduler depends upon the presence of the tool sets shown in Table 19-2 and 
requires that at least the indicated version of the tool set be present. 

Table 19-2 

Scheduler—other tool sets required 

Tool set Tool set Minimum version 

number name needed 


$01 #01 Tool Locator 1.0 

Your application should make a SchStartUp call before making any other Scheduler 

calls. 

❖ Note: At the time of publication, the SchStartUp call was not an absolute 
requirement, because the Tool Locator automatically started up the Scheduler at 
boot time. However, you should make the call anyway to guarantee that your 
application remains compatible with all future versions of the system. 

Your application should also call SchShutDown when the application quits. 
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The Scheduler revolves around the busy flag located at $E1/(X)FF. If you wish to 
change the state of the busy flag, you should use the routines INCBUSYFLG and 
DECBUSYFLG. Those routines are not tool set routines, but are accessed directly 
from vectors in bank $E1 as follows: 

INCBUSYFLG $El/0064 

DECBUSYFLG $El/0068 

When a nonreentrant module is entered, your tool set or interrupt handler should 
perform a JSL to INCBUSYFLG in full native mode (e, m, and x flags all set to 0). 
When exiting from the module, the application should perform a JSL to 
DECBUSYFLG. DECBUSYFLG decrements the busy flag and executes any tasks 
placed in the Scheduler queue with the tool set routine SchAddTask. 

Your tool set or interrupt handler should use SchAddTask after it checks the state of 
the busy flag. If the flag is set to other than 0, the necessary system resources are not 
currently available, and you can add a task to the Scheduler queue by using the 
SchAddTask routine. 

Note that your application should never call the SchFlush routine. 


Using the Scheduler 
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$0107 

SchBootInit 

Initializes the Scheduler; called only by the Tool Locator. 

Warning 

An application must never make this call. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call must not be made by an application. 


$0207 

SchStartUp 

Starts up the Scheduler for use by an application. 

❖ Note: At the time of publication, the SchStartUp call was not an absolute 
requirement, because the Tool Locator automatically started up the Scheduler at 
boot time. However, you should make the call anyway, to guarantee that your 
application remains compatible with all future versions of the system. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void SchStartUp{) 
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$0307 SchShutDown 

Shuts down the Scheduler when an application quits. 


Important 

If your application has started up the Scheduler, the application must make this 
call before It quits. 


Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C extern pascal void SchShutDown() 


$0407 


Parameters 


SchVersion 

Returns the version number of the Scheduler. 


Stack before call 

previous contents 


wordspace 


Word—Space for result 
<—SP 


Stack after call 
previous contents 


versioninfo 


Errors 

C 


Word—^Version number of Scheduler 
<—SP 


None 

extern pascal Word SchVersion() 


Scheduler housekeeping routines 
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$0507 Sch Reset 

Resets the Scheduler, called only when the system is reset. 

Warning 

An application must never make this call. 

Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C Call must not be made by an application. 


$0607 SchStatus 

Indicates whether the Scheduler is active. 

Parameters 

Stack before call 
previous contents 

wordspace Word —Space for result 

^SP 


Stack after call 


previous contents 
activeFlag 


Word —^BOOLEAN; TRUE if Scheduler active, FALSE if inactive 

<— SP 


Errors None 

C extern pascal Boolean SchStatus<) 
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$0907 SchAddTask 

Adds a task to the Scheduler queue. The queue has space for fovir items, enough to 
support the Desk Manager as well as other small interrupt handlers. 

The Scheduler uses a JSL to launch the procedure pointed to by taskPtr. If the task 
can’t be added to the queue because the queue is already full, onQueueFlag will be 
FALSE. 

»> Note; The Scheduler is not designed to support multitasking. 

When the busy flag is decremented to 0, the tasks in the queue are executed in the 
posted order. 


Parameters 
Stack before call 

Word— ^Space for result 
Long— POINTER to task to be added 
<—SP 


previous contents 
wordspace 


taskPtr 


Stack after call 


previous contents 
onQueueFlag 


Word —BOOLEAN; TRUE if task added to Scheduler’s queue, 
SP FALSE if queue was full 


Errors None 


C 


extern pascal Boolean SchAddTask(taskPtr) 
VoidProcPtr taskPtr; 


Scheduler routines 
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$0A07 

SchFlush 

Hushes all tasks in the Scheduler’s queue. 

Important 

An application must never make this call. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call must not be made by an application. 


Scheduler summary 

Tlie Scheduler does not contain any predefined constants, data structures, or tool set 
error codes. 
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Chapter 20 


Scrap Manager 


The Scrap Manager lets an application handle cutting and pasting. From the user’s 
point of view, all data that is cut or copied resides in the Clipboard. The Cut 
command deletes data from a document and places it in the Clipboard. The Copy 
command copies data into the Clipboard without deleting it from the document. A 
subsequent Paste command will insert the contents of the Clipboard at a specified 
place, whether that place is in the same document or another or in the same 
application or another. An application that supports cutting and pasting may also 
provide a Clipboard window for displaying the current contents of the scrap; it may 
show the Clipboard window at all times or only when requested via the Show (or 
Hide) Clipboard command. 

❖ Note: The Scrap Manager is intended to transfer limited amounts of data; 
attempts to transfer very large amounts of data may fail due to lack of memory. 

The nature of the data to be transferred varies according to the application. For 
example, in a word processor, the data is text; in a graphics application, it’s a 
picture. The amount of information retained about the data being transferred also 
varies. Between two text applications, text can be cut and pasted without any loss of 
information; however, if the user of a graphics application cuts a picture consisting 
of text and then pastes it into a word processor document, the text in the picture may 
not be editable in the word processor, or it may be editable but not look exactly the 
same as in the graphics application. The Scrap Manager allows for a variety of data 
types and provides a mechanism whereby applications have some control over how 
much information is retained when data is transferred. 

The desk scrap is usually stored in memory, but can be stored on the disk (in the file 
CLIPBOARD in the SYSTEM subdirectory of the boot volume) if there’s not enough 
room for it in memory. 

❖ Macintosh programmers: The scrap does not have to be in memory when an 
application starts or stops. 









A preview of the Scrap Manager routines 

To introduce you to the capabilities of the Scrap Manager, all Scrap Manager 
routines are grouped by function and briefly described in Table 20-1. These routines 
are described in detail later in this chapter, where they are separated into 
housekeeping routines (discussed in routine number order) and the rest of the Scrap 
Manager routines (discussed in alphabetical order). 

Table 20-1 

Scrap Manager routines and their functions 
Routine Description 


Housekeeping routines 
ScrapBootlnit 

ScrapStartUp 

ScrapShutDown 

ScrapVersion 

ScrapReset 

ScrapStatus 


Initializes the Scrap Manager; called only by the Tool Locator—must not be called 
by an application 

Starts up the Scrap Manager for use by an application 
Shuts down the Scrap Manager when an application quits 
Returns the version number of the Scrap Manager 

Resets the Scrap Manager; called only when the system is reset—^must not be 

called by an application 

Indicates whether the Scrap Manager is active 


Scrap routines 
UnloadScrap 

LoadScrap 

ZeroScrap 

PutScrap 

GetScrap 


GetScrapCount 

GetScrapState 

GetScrapHandle 

GetScrapSize 

GetScrapPath 

SetScrapPath 


Writes the desk scrap from memory to the scrap file and releases the memory it 
occupied 

Reads the desk scrap from the scrap file into memory 

Clears the contents of the scrap and increments the scrap count 

Appends specified data to the scrap that has the same scrap type as the data 

Copies scrap information of the appropriate type to a specified handle, setting 

the handle to the correct size 

Returns the current scrap count 

Returns a flag indicating the current state of the scrap 

Returns a copy of the handle for the scrap of a specified type 

Returns the size of the specified scrap 

Returns a pointer to the pathname used for the Clipboard file 

Sets a pointer to the pathname used for the Clipboard file 
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Memory and the desk scrap 

A large desk scrap can prevent an application from being loaded. If your application 
needs to know about whether there’s enough room for the desk scrap in memory, you 
can set up your application so that a small initial segment of it is loaded. That 
segment can contain a Scrap Manager call to get the scrap size. 

After a decision is made about whether to keep the scrap in memory or on disk, the 
remaining segments of the application can be loaded as needed. Of course, if there 
isn’t enough room for the scrap at application load time, there probably won’t be 
room for it later when a user tries to paste its contents into a document. 

There are other disadvantages to keeping the desk scrap on disk: The disk may be 
locked, it may not have enough room for the scrap, or it may be removed during use 
of the application. 


Important 

If the application can't write the scrap to disk. It should put up an alert box 
Informing the user, who may want to cancel the operation at that point. 


Desk scrap data types 

From the user’s point of view there can be only one item on the Clipboard at a time, 
but the application may store more than one version of the information in the scrap, 
each representing the same Clipboard contents in a different form. For example, 
text cut from a word processor document may be stored in the desk scrap both as text 
and as a QuickDraw II picture. 

Why would you want to do this? You might want your application to keep information 
in its own internal format, but you may also want it to be able to communicate via the 
Clipboard with other applications. When a user cuts or copies something to the 
Clipboard, the application can put it there in two different ways: 

1. It can put it there internally so that a subsequent paste operation can be easily 
handled. 

2. It can put it there publicly so that if the user tries to paste it into another 
application or desk accessory, the other application can handle it. 


Desk scrap data types 
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There are two public scrap types, as shown in Table 20-2. 


Table 20-2 
Public scrap types 


Value Name 


Scrap type 


0 

1 


text Scrap Text 
picScrap Picture 


Applications must write at least one of these standard types of data to the desk scrap 
and must be able to read both types. Most applications will prefer one of these types 
over the other; for example, a word processor prefers text, whereas a graphics 
application prefers pictures. An application should write at least its preferred 
standard type of data to the desk scrap, and it may write both types (to pass the most 
information possible to the receiving application, which may prefer the other type). 

An application reading the desk scrap looks for its preferred data type. If the 
application’s preferred type isn’t there—or if it’s there but it was written by an 
application having a different preferred type—the receiving application may or may 
not be able to convert the data to the type it needs. If it cannot, some information 
may be lost in the transfer process. For example, a graphics application can easily 
convert text to a picture, but the reverse isn’t true. 


Using the Scrap Manager 


This section discusses how the Scrap Manager routines fit into the general flow of an 
application and gives you an idea of which routines you’ll need under normal 
circumstances. Each routine is described in detail later in this chapter. 

The Scrap Manager depends upon the presence of the tool sets shown in Table 20-3 
and requires that at least the indicated version of the tool set be present. 

Table 20-3 

Scrap Manager — other tool sets required 

Tool set Tool set Minimum version 

number name needed 


$01 #01 Tool Locator 1.0 

$02 #02 Memory Manager 1.0 

The first Scrap Manager call that your application must make is SaapStartUp. 
Conversely, when you quit your application, you must call ScrapShutDown. 
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If your application supports display of the Clipboard, you can call GetScrapCount to 
find out whether a desk accessory has changed the desk scrap. The scrap count 
indicates how many times the scrap has changed. Save the value of this field when 
one of your application's windows is deactivated and a system window is activated. 
Check the value each time through the main event loop to see whether it has 
changed; if it has, the contents of the desk scrap have changed. If the Clipboard 
window is visible, it needs to be updated whenever the count changes. 

When the user gives a Cut or Copy command, your application needs to write the cut 
or copied data to the desk scrap. First call ZeroScrap to clear its previous contents; 
then call PutScrap to put the data into the scrap. If it makes it easier for your 
application to transfer data, you can call PutScrap more than once with the same 
scrap type. 

When the user gives a Paste command, call GetScrap to access data of a particular 
type in the desk scrap and to get information about the data. 

❖ Note: ZeroScrap, PutScrap, and GetScrap all keep track of whether the scrap is in 
memory or on the disk, so you don't have to worry about loading it first. After 
any of these calls, the scrap will be in memory again. 


Setting up a private scrap 

Instead of using the desk scrap for storing data that’s cut and pasted within an 
application, you may want to set up a private scrap for this purpose. 

❖ Note: In most applications that use the standard text or picture data types, it's 
simpler for the application to use the desk scrap. However, if your application 
defines its own private type of data, or if very large amounts of data might be cut 
and pasted, using a private scrap may result in faster cutting and pasting within 
the application. 

The format of a private scrap can be anything you want, because no other application 
will use it. For example, an application can simply maintain a pointer to cut or 
copied data. The application must, however, be able to convert data between the 
format of its private scrap and the format of the desk scrap. 

❖ Note: The LineEdit scrap is a private scrap for applications that use LineEdit. 
LineEdit provides routines that access its own scrap and transfer data between the 
LineEdit scrap and the desk scrap. 


Setting up a private scrap 
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If you use a private scrap, you must be sure that the right data is always pasted when 
the user gives a Paste command (the right data being whatever was most recently cut 
or copied in any application or desk accessory) and that the Clipboard, if visible, 
always shows the current data. You should copy the contents of the desk scrap to your 
private saap at application startup and whenever a desk accessory is deactivated (call 
GetScrap to access the desk scrap). When the application is terminated, or when a 
desk accessory is activated, you should copy the contents of the private scrap to the 
desk scrap. Call ZeroScrap to clear its previous contents; call PutSaap to write data 
to the desk scrap. 

If transferring data between the two scraps means converting it, and possibly losing 
information, you can copy the scrap only when you actually need to, at the time 
something is cut or pasted. The desk scrap needn’t be copied to the private scrap 
unless one of the following conditions is true: 

■ A Paste command is given before the first Cut or Copy command after the 
application starts up. 

■ A desk accessory that changed the scrap was deactivated. 

Until then, you must keep the contents of the desk scrap intact. If the Clipboard 
window is visible, you must display the desk scrap, instead of the private scrap, in 
that window. 

After one of the preceding conditions has occurred, you can ignore the desk scrap 
until a desk accessory is activated or the application is terminated; in either of these 
cases, you must copy the private scrap back to the desk scrap. Thus, whatever was last 
cut or copied within the application is pasted if a Paste command is given in a desk 
accessory or in the next application. If no Cut or Copy commands are given within 
the application, you never have to change the desk scrap. 

If your application encounters problems in trying to copy one scrap to another, it 
should alert the user. If the desk scrap is too large to copy to the private scrap, the 
user may want to leave the application or simply proceed with an empty Clipboard. 

If the private saap is too large to copy to the desk scrap, either because it’s disk based 
and too large to copy into memory or because it exceeds the maximum size allowed 
for the desk saap, the user may want to stay in the application and cut or copy a 
smaller item. 
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$0116 

ScrapBootInit 

Initializes the Scrap Manager; called only by the Tool Locator. 

Warning 

An application must never make this call. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call must not be made by an application. 


$0216 

ScrapStartUp 

Starts up the Scrap Manager for use by an application. 

Important 

Your application must make this call before It makes any other Scrap Manager 
calls. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void ScrapStartUp() 


Scrap Manager housekeeping routines 
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$0316 ScrapShutDown 

Shuts down the Scrap Manager. 


Important 

If your application has started up the Scrap Manager, the application must make 
this call before It quits. 


Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C extern pascal void ScrapShutDown() 


$0416 ScrapVersion 

Returns the version number of the Scrap Manager. 

Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

SP 


Stack after call 
previous contents 

versioninfo Word—^Version number of the Scrap Manager 

SP 

Errors None 

C extern pascal Word ScrapVersion() 
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$0516 ScrapReset 

Resets the Scrap Manager; called only when the system is reset. 

Warning 

An application must never make this call. 

Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C Call must not be made by an application. 


$0616 ScrapStatus 

Indicates whether the Scrap Manager is active. 

Parameters 

Stack before call 
previous contents 

wordspace Word —Space for result 

<—SP 


Stack after call 

previous contents 
activeFlag 


Word —BOOLEAN; TRUE if Scrap Manager active, FALSE if inactive 
<—SP 


Errors None 

C extern pascal Boolean ScrapStatus() 
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$0D16 GetScrap 

Copies scrap information of the appropriate type to a specified handle, setting the 
handle to the correct size. 

❖ Note: To copy the desk scrap to the LineEdit scrap, use the LineEdit routine 
LEFromScrap. 

Parameters 

Stack before call 
previous contents 
destHandle 


scrapType 


Long—HANDLE to scrap destination 

Word—Scrap type; picScrap, textScrap, or application defined 
<—SP 


Stack after call 
previous contents 


Errors 


<— SP 

$1610 badScrapType 
Memory Manager errors 
ProDOS errors 


No scrap of this type found 
Returned unchanged 
Returned unchanged 


extern pascal void GetScrap(destHandle,scrapType) 
Handle destHandle; 

Word scrapType; 
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$1216 GetScrapCount 

Returns the current scrap count. The count changes every time ZeroScrap is called. 
You can use this count for testing whether the contents of the desk scrap have 
changed; if ZeroScrap has been called, presumably PutScrap has also been called. 
This information may be useful if your application supports display of the Qipboard 
or has a private scrap. 


Paranneters 

Stack before call 

previous contents 

wordspace Word—Space for result 

^SP 


Stack after call 
previous contents 

scrapCount Word— ^INTEGER; current scrap count 

SP 

Errors None 

C extern pascal unsigned int GetScrapCount() 
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$0E16 GetScrapHandle 

Returns a copy of the handle for the scrap of a specified type. 

GetScrapHandle allows you to access the scrap without making a copy of it, which 
might be important when memory is in short supply. 

Parameters 


Stack before call 

previous contents 


longspace 

— 

scrapType 



Long—Space 

Word—Scrap 
<—SP 


for result 

type; picScrap, textScrap, or application defined 


Stack after call 


previous contents 
— scrapHandle 


Long—HANDLE to specified type of scrap 

<—SP 


Errors 


C 


$1610 badScrapType 
Memory Manager errors 
ProDOS errors 


No scrap of this type found 
Returned unchanged 
Returned unchanged 


extern pascal Handle GetScrapHandle(scrapType) 
Word scrapType; 
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$1016 GetScrapPath 

Returns a pointer to the pathname used for the Clipboard file. 

Parameters 

Stack before call 

previous contents 

longspace — Long—Space for result 

<— SP 


Stack after call 

previous contents 
pathPtr 


Long—POINTER to pathname 
<— SP 


Errors None 

C extern pascal Pointer GetScrapPathO 
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$0F16 


GetScrapSize 

Returns the size of a specified scrap. 


Parameters 

Stack before call 

Long—Space for result 

Word—Scrap type; picScrap, textScrap, or application defined 
<—SP 


previous contents 


longspace 


scrapiype 


Stack after call 


previous contents 


scrapSize 


Long—Size of scrap in bytes 


<—SP 


Errors 


C 


$1610 badScrapType No scrap of this type found 

Memory Manager errors Returned unchanged 

ProDOS errors Returned unchanged 

extern pascal LongWord GetScrapSize(scrapType) 

Word scrapType; 
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$1316 GetScrapState 

Returns a flag indicating the current state of the scrap. The scrapState flag is set to a 
nonzero value if the scrap is in memory; it is set to 0 if the scrap is currently on disk. 

❖ Note: The scrapState flag is actually 0 if the scrap should be on disk. The scrap 
may not be on disk because a user can delete the Clipboard file. 


Parameters 


Stack before call 


previous contents 
wordspace 


Word—^Space for result 
<—SP 


Stack after call 

previous contents 

scrapState Word—INTEGER; nonzero if scrap in memory, 0 if on disk 

<—SP 

Errors None 

C extern pascal Word GetScrapState() 


$0A16 LoadScrap 

Reads the desk scrap from the scrap file into memory. If the desk saap is already in 
memory, it does nothing. If the Clipboard file cannot be found, no error is returned; 
the computer responds as if you had loaded an empty Clipboard file. 

Parameters The stack is not affected by this call. There are no input or output parameters. 


Errors 


Memory Manager errors Returned unchanged 

ProDOS errors Returned unchanged 


C 


extern pascal void LoadScrap() 
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$0016 PutScrap 

Appends specified data to the scrap that has the same type as the data. If the scrap is 
on disk, the scrap is loaded. 


Important 

Don't forget to call ZeroScrap if you want to clear the scrap's previous contents. 
If you don't call ZeroScrap. the data Is appended to the existing scrap. 

❖ Note: To copy the LineEdit scrap to the desk scrap, use the LineEdit routine 
LEToScrap. 

Parameters 

Stack before call 

previous contents 
numBytes 
scrapType 
srcPtr 


Long —LONGINT; number of bytes to write 

Word —Scrap type; picScrap, textScrap, or application defined 
Long —POINTER to data to be placed in scrap 
<r- SP 


Stack after call 


previous contents 


^SP 


Errors 


C 


Memory Manager errors Returned unchanged 

ProDOS errors Returned unchanged 

extern pascal void PutScrap(numBytes,scrapType,srcPtr) 
unsigned Longint numBytes; 

Word scrapType; 

Pointer srcPtr; 
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$1116 SetScrapPath 

Sets a pointer to the pathname used for the Clipboard file. 

Parameters 

Stack before call 

previous contents 

pathPtr — Long—POINTER to pathname of Clipboard 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetScrapPath(pathPtr) 

Pointer pathPtr; 


$0916 UnloadScrap 

Writes the desk scrap from memory to the scrap file and releases the memory the desk 
scrap occupied If the desk saap is already on disk, UnloadScrap does nothing. 

Parameters The stack is not affected by this call There are no input or output parameters. 

Errors Memory Manager errors Returned unchanged 

ProDOS errors Returned unchanged 

C extern pascal void UnloadScrap() 
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$0B16 

ZeroScrap 

Clears the contents of the scrap, whether the scrap is memoiy or on disk, and also 
changes the saap count. When the user selects Cut or Copy, your application should 
call ZeroScrap before it calls PutScrap. 

Parameters 

The stack is not affected by this call There are no input or output parameters. 

Errors 

Memory Manager errors Returned unchanged 

ProDOS errors Returned unchanged 

C 

extern pascal void ZeroScrap() 
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Scrap Manager summary 

This section briefly summarizes the constants and tool set error codes contained in 
the Scrap Manager. There are no predefined data structures for the Scrap Manager. 


Important 

These definitions are provided In the appropriate Interface file. 


Table 20-4 

Scrap Manager constants 


Name Value Description 


Public scrap type 

text Scrap $0000 Text scrap 

picScrap $0001 Picture scrap 

Table 20-5 

Scrap Manager error codes 


Code Name Description 


$l6l0 badScrapType No scrap of this type found 
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Chapter 21 


Sound Tool Set 


The Sound Tool Set gives you the ability to access the sound hardware without 
having to know specific hardware input/output addresses. 

Sound Tool Set calls (other than the standard housekeeping routines) can be broken 
down into two groups. The first group is made through the normal tool call 
mechanism, with parameters being passed to and from the called routines on the 
stack. The second group is composed of low-level routines that, unlike most tool 
calls, use an eight-bit accumulator, pass their parameters in registers, and are 
accessed through a jump table. 

There are two other tool sets dealing with sound—the Note Synthesizer and the Note 
Sequencer. These tool sets are not documented in the Apple JIGS Toolbox 
Reference. At the time of publication, documentation of these tool sets is planned 
for another, as yet unnamed, book. 

Note: This chapter uses the terms Note Synthesizer znd Free-Form 
Synthesizer. In the world of Apple sound, these terms refer to specific tool sets 
and not to electronic musical instruments. 


A preview of the Sound Tool Set routines 

To introduce you to the capabilities of the Sound Tool Set, all Sound Tool Set 
routines are grouped by function and briefly described in Table 21-1. These routines 
are described in detail later in this chapter, where they are separated into 
housekeeping routines (discussed in routine number order), the rest of the numbered 
routines (discussed in alphabetical order), and the low-level routines. 


Important 

The low-level routines do not hove tool set routine names and thus do not fit 
the alphabetical order organization; instead, they are organized in Jump table 
offset order. Also note that the low-level routines do not have routine numbers. 









Table 21-1 

Sound Tool Set routines and their functions 


Routine 

Description 

Housekeeping routines 

SoundBootInit 

Initializes the Sound Tool Set; called only by the Tool Locator—^must not be 
called by an application 

SoundStartUp 

SoundShutDown 

SoundVersion 

SoundReset 

Starts up the Sound Tool Set for use by an application 

Shuts down the Sound Tool Set 

Returns the version number of the Sound Tool Set 

Resets the Sound Tool Set; called only when the system is reset—must not be 
made by an application 


SoundToolStatus Indicates whether the Sound Tool Set is active 

RAM and volume routines 

WriteRamBlock Writes a specified number of bytes from system RAM into DOC RAM 


ReadRamBlock 

GetSoundVolume 

SetSoundVolume 

Reads a specified number of bytes from from DOC RAM into system RAM 

Reads the volume setting for a generator 

Changes the volume setting for the volume registers in the DOC or changes the 
system volume 


GetTableAddress Returns the jump table address for the low-level routines 

Free-Form Synthesizer routines 


FFStartSound 

FFStopSound 

FFSoundStatus 

FFGeneratorStatus 

Enables the DOC to start generating sound on a particular generator 

Halts any specified sound generators that are generating sound 

Returns the status of all 15 sound generators 

Reads the first two bytes of the generator control block corresponding to a 
specified generator 

SetSoundMIRQV 
SetUserSoundIRQV 
FFS oundD one Status 

Sets up the entry point into the sound-interrupt handler 

Sets up the entry point for an application-defined synthesizer interrupt handler 
Returns the current Free-Form Synthesizer playing status 

Low-ievel routines 

Read Register 

Write Register 

Read RAM 

Write RAM 

Read Next 

Write Next 

Reads any register in the DOC 

Writes a onebyte parameter to any register in the DOC 

Reads any specified DOC RAM location 

Writes a one-byte value to any specified DOC RAM location 

Reads the next location pointed to by the Sound GLU address register 

Writes one byte of data to the next DOC register or RAM location, depending 
on the setting of the Sound GLU control register 

Disable Increment 

Disables the auto-increment mode set up by a Read Register, Write Register, 
Read RAM, or Write RAM low-level sound routine, thus allowing your 
application to read a DOC register or memory location continuously 
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Sound hardware 

The Apple IIGS sound hardware supports two sound subsystems. The first subsystem 
is an extension of the Apple lie sound capabilities. Using this subsystem, 
applications toggle a soft switch, which in turn generates clicks in a speaker. In 
addition, the IIGS allows the application to control the volume of the speaker. 

The second subsystem uses a digital oscillator chip (pOC) and 64K of dedicated 
RAM. The Sound Tool Set contains all of the firmware routines required to access the 
sound hardware. Figure 21-1 shows the major functional blocks of the sound 
hardware. 



Figure 21-1 

Sound hardware block diagram 


Sound hardware 
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The sound GLU (general logic unit) acts as the interface chip between system 
hardware and sound hardware. Figure 21-2 shows the sound GLU registers. 
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Figure 21-2 

Sound GLU registers 

The DOC RAM stores the waveforms used for sound generation. The DOC can create 
sounds of any pitch and duration. Table 21-2 shows the DOC registers. 

Table 21-2 

DOC register allocation 


Register Bits 


number 

Function 

D7 

D6 

D5 

D4 

D3 

D2 

D1 

DO 

$00-lF 

Frequency low 

FL7 

fl6 

FL5 

FL4 

FL3 

FL2 

FLl 

FLO 

$20-3F 

Frequency high 

FH7 

fh6 

FH5 

FH4 

FH3 

FH2 

FHl 

FHO 

$40-5F 

Volume 

V7 

v6 

V5 

V4 

V3 

V2 

VI 

VO 

$60-7F 

Data sample 

W7 

w6 

W5 

W4 

W3 

W2 

W1 

WO 

$80-9F 

Waveform table pointer 

P7 

p6 

P5 

P4 

P3 

P2 

PI 

PO 

$A0-BF 

Control 

CA3 

CA2 

CAl 

CAO 

IE 

M2 

Ml 

H 

$C0-DF 

Bank select/table size/resolution 

X 

BS 

T2 

T1 

TO 

R2 

R1 

RO 

$E0 

Oscillator interrupt 

IRQ 

1 

04 

03 

02 

01 

00 

1 

$E1 

Oscillator enable 

X 

X 

E4 

E3 

E2 

El 

EO 

X 

$E2 

Analog/digital converter 

S7 

S6 

S5 

S4 

S3 

S2 

SI 

SO 
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For further information on the DOC, see the Apple IIGS Hardware Reference. 

The analog section contains all the circuitry needed to amplify and filter the signal 
coming from the sound GLU or the DOC, The signal will be sent to the speaker. 

The sound connector provides the connection to interface cards that can take the 
tones generated by the DOC and modify them fijrther. Two examples of possible 
sound cards are programmable filter stereo interface cards and sound sampling 
cards. 


Oscillators and generators 

An oscillator is the basic sound-generating unit in the DOC. The DOC contains 32 
oscillators, each of which can function independently from all the other oscillators. 

One of the modes of the DOC is called swap mode. The Free-Form Synthesizer uses 
this mode to generate sounds. In swap mode, a pair (or swap pair) of oscillators 
form a functional oscillator unit called a generator. There are 15 generators 
defined in the Apple IIGS sound system. An oscillator-to-generator translation table 
converts an oscillator number to the appropriate generator number. That table is 
accessed through the jump table shown in the section “GeiTableAddress” in this 
chapter. 

Each oscillator controls seven DOC registers in the range 00-DF, as shown in 
Table 21-3. 


Table 21-3 
Oscillator registers 


Register 

function 

Oscillator 0 
registers 

Oscillator 1 
registers 

Oscillator n 
registers 

Oscillator 31 
registers 

Frequency low 

$00 

$01 

$00 + n ... 

$1F 

Frequency high 

$20 

$21 

$20 + n ... 

$3F 

Volume control 

$40 

$41 

$40 + « ... 

$5F 

Data sampling 

$60 

$61 

$60 + « ... 

$7F 

Waveform table pointer 

$80 

$81 

$80 + n 

$9F 

Control register 

$A0 

$A1 

$A0 + n ... 

$BF 

Bank select/table size/resolution 

$C0 

$C1 

$C0 + w ... 

$DF 


Oscillators 30 and 31 are reserved for system use and should not be used by 
applications. If an interrupt is generated by oscillator 30 or 31, control is passed to 
the System Failure Manager with an “unclaimed sound interrupt” message. When the 
SoundBootInit routine is called by the system at boot time, all of the sound interrupt 
handler pointers point to the System Failure Manager with this message. 


Oscillators and generators 
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The work area for the sound routines (specified in the SoundStartUp calD is broken 
down into 16 groups of l6 bytes each, with each l6-byte group comprising one 
generator control block (GCB). The first byte of each contains the synthesizer 
type being used by that generator. The high nibble is reserved for use by the system 
and must be zero. The low nibble of the byte (bits 3-0) contains the type. The 
remaining 15 bytes in the GCB are for use by the application, and their meaning and 
value may vary depending on the synthesizer type. 


Using the Sound Tool Set 

This section discusses how the Sound Tool Set routines fit into the general flow of an 
application and gives you an idea of which routines youll need to use under normal 
circumstances. Each routine is described in detail later in this chapter. 

The Sound Tool Set depends on the presence of the tool sets shown in Table 21-4, 
and requires that at least the indicated version of the tool set be present. 

Table 21-4 

Sound Tool Set—other tool sets required 

Tool Set Tool Set Minimum version 

number name needed 


$01 #01 Tool Locator 1,0 

$02 #02 Memory Manager 1.0 

Your application must make the SoundStartUp call before it makes any other Sound 
Tool Set calls. Conversely, when your application quits, it must make the 
SoundShutDown call. 

The Sound Tool Set gives you the ability to control the sound hardware without 
having to access the hardware registers directly. To provide this capability, the 
Sound Tool Set must be able to read and write to RAM, read and write to the DOC 
registers, and raise and lower the volume. This requires a set of low-level sound 
routines. Unlike the other Sound Tool Set routines, which use the stack to pass 
parameters in the normal tool call fashion, these routines use registers to pass 
parameters. 

❖ Note: Because the low-level sound routines have been designed and 
implemented to increase performance, they may not be available in all 
programming languages. At the time of publication, for example, the low-level 
sound routines were not available from Apple IIGS Workshop C. 

The low-level routines are entered through a jump table. The table address can be 
obtained through a call to the GetTableAddress routine. The actual format of the 
jump table is shown in the section “GetTableAddress” in this chapter. 
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$0108 


SoundBootlnit 

Initializes the Sound Tool Set; called only by the Tool Locator. 


Parameters 

Errors 

C 


Warning 

An application must never make this call. 

This routine performs the following: 

■ Resets all of the DOC RAM 

■ Resets the Sound Tool Set’s work area 

■ Resets the oscillators to an uninitialized state 

The stack is not affected by this call. There are no input or output parameters. 
None 

Call must not be made by an application. 
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$0208 SoundStartUp 

Starts up the Sound Tool Set for use by an application. The direct page must be page- 
aligned and locked until the SoundShutDown call is made. 


Important 

Your application must make this call before It makes any other Sound Tool Set 
calls. 


Parameters 

Stack before call 

Word —Bank $0 starting address of one page of direct-page space 
<—SP 


previous contents 
dPageAddr 


Stack after call 

previous contents I 

1<- SP 

Errors $0810 noDOCFndErr No DOC or RAM found 

$0818 sndAlreadyStrtErr Sound tools already started 

C extern pascal void SoundStartUp(dPageAddr) 

Word dPageAddr; 
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$0308 


SoundShutDown 

Shuts down the Sound Tool Set. 


Important 

If your application has started up the Sound Tool Set, the application must make 
this call before It quits. 


Parameters TTie stack is not affected by this call. There are no input or output parameters. 
Errors None 

C extern pascal void SoundShutDown() 


$0408 SoundVersion 

Returns the version number of the Sound Tool Set. 

Parameters 

Stack before call 
previous contents 

wordspace Word—Space for result 

SP 


Stack after call 


previous contents 
versioninfo 


Word—^Version number of Sound Tool Set 
SP 


Errors None 

C extern pascal Word SoundVersion{) 
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$0508 SoundReset 

Resets the Sound Tool Set; called only when the system is reset. 


Warning 

An application must never make this call. This call Is used only by the system to 
control the shutdown of generators. If you want to shut down a generator, use 
the StopSound routine. 


Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C Call must not be made by an application. 


$0608 SoundToolStatus 

Indicates whether the Sound Tool Set is active. 

Parameters 

Stack before call 

previous contents 

wordspace Word —Space for result 

<—SP 


Stack alter call 


previous contents 
activeFlag 


Word— BOOLEAN; TRUE if Sound Tool Set active, FALSE if inactive 
<—SP 


Errors None 

C extern pascal Boolean SoundToolStatus() 
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$1108 FFGeneratorStatus 

Reads the first two bytes of the generator control block that corresponds to a specified 
generator. 


Parameters 

Stack before call 


Word —Space for result 

Word —Number of generator whose status will be returned 

SP 


previous contents 
wordspace 
genNumber 


Stack after call 


previous contents 
genStatus 


Word —Status of genNumber isee Figure 21-3) 
SP 


Errors None 

C extern pascal Word FFGeneratorStatus(genNumber) 

Word genNumber; 


(continued) 
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Generator status word 

The status returned in the genStatus parameter is in the format shown in Figure 21-3. 
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Generator number ($00-$0E) - 


Figure 21-3 

Generator status word 
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$1408 FFSoundDoneStatus 

Returns the current Free-Form Synthesizer playing status. If the specified generator is 
currently playing out a waveform, the status returned to the caller will be TRUE. If the 
generator is not playing, the status will be FALSE ($FFFF). 


Paranneters 

Stack before call 


Word—Space for result 

Word—^Number of generator whose status will be returned 
SP 


previous contents 
wordspace 
genNumber 


Stack after call 
previous contents 

genDoneFlag Word—^BOOLEAN; status of genNumber; TRUE if done playing, 

<— SP FALSE if playing 

Errors $0813 invalGenNumErr Invalid generator number 

C extern pascal Boolean FFSoundDoneStatus(genNumber) 

Word genNumber; 
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$1008 FFSoundStatus 

Returns the status of all 15 sound generators. Any bit position set to 1 in the status 
word returned from the function call signifies that the corresponding generator is 
active. The format of the status word returned is the same as that of the stop-sound 
mask as illustrated in Figure 21-6 in the section “FFStopSound,” with bit 0 
corresponding to generator 0, bit 1 corresponding to generator 1, and so on. 


Parameters 


Stack before call 


previous contents 
wordspace 


Word —Space for result 

SP 


Stack after call 

previous contents 

genStatusInfo Word —^Status of all generators (bit 0 = generator 0 and so on) 

SP 

Errors None 

C extern pascal Word FFSoundStatus() 
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$0E08 FFStartSound 

Enables the DOC to start generating sound on a particular generator. If this call is 
made to a generator that is already active, the previous sound-generation process is 
terminated and the new sound process is started. 

Parameters 


Stack before call 

previous contents 
genNumFFSynth 

pBlockPtr 


Word—Channel, generator, and type (see Figure 21-4) 

Long—POINTER to parameter block for sound (see Figure 21-5) 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors 

$0812 

noSAppInitErr 

No SoundStartUp call made 


$0813 

invalGenNumErr 

Invalid generator number 


$0814 

synthModeErr 

Synthesizer mode error 


$0815 

genBusyErr 

Generator already in use 

C 

extern 

Word 

Pointer 

pascal void FFStartSound(genNumFFSynth,pBlockPt: 

genNumFFSynth/ 

pBlockPtr; 


(continued) 
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Channel-generator-type word 

The values for the channel-generator-type word are shown in Figure 21-4. 
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Generator number ($0“$E) -* 

Reserved for future use; must be 0 -* 
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Note Synthesizer = $02 
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Application-defined = $08-$0F 


Figure 21-4 

Channel-generator-type word 
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Parameter block 


The values for the parameter block are shown in Figure 21-5. The effective output 
sample rate can be calculated as follows: 

freqOffiet = ((32 x Output sample rate in hertz)/l645) 

For more detailed information on these settings, refer to the Apple HGS Hardware 
Reference. 

Offset Field 


Long— Starting address of wave 


Word— Waveform size in pages 


Word— Output sample rate 


Word— DOC buffer start address; 

hIgh-order byte significant, low-order byte = 0 

Word— DOC buffer size; 

high-order byte = 0, low-order byte significant 


Long— POINTER to start of next wave’s parameter block 


Word— DOC volume setting; 

hIgh-order byte = 0, low-order byte significant 

Figure 21-5 

Sound parameter block 
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$OFOd FFStopSound 

Halts any specified sound generators that are generating sound. Depending on the 
setting of a l6-bit mask passed as a parameter to the routine, any of 15 generators will 
be stopped if running. Each bit position in the stop-sound mask corresponds to a 
sound generator. Bit 0 corresponds to generator 0, bit 1 corresponds to generator 1, 
and so on, up to bit 15 (bit 15 must be 0). Figure 21-6 illustrates the stop-sound mask. 


Parameters 

Stack before call 

Word —^Mask to stop generators (see Figure 21-6) 
«-SP 


previous contents 
genMask 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void FFStopSound(genMask) 

Word genMask; 


stop-sound mask 

The values for the stop-sound mask are shown in Figure 21-6. 
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Ini 14113 


12 

0 

10 

0 

0 

0 

0 

5 

0 

0 

0 

0 

0 


Reserved; must be 0 


y 


gen 14off —* 
Generator 14 off = 1 
Generator 14 on = 0 

gen 13off 

Generator 13 off = 1 
Generator 13 on = 0 


genl2off-^ 
Generator 12 off = 1 
Generator 12 on = 0 

genlloff-^ 
Generator 11 off = 1 
Generator 11 on = 0 


gen lOoff 

Generator lOoff = 1 
Generator 10 on » 0 

gen9off 

Generator 9 off = 1 
Generator 9 on = 0 


gendoff-^ 
Generator 8 off = 1 
Generator 8 on = 0 

gen7off -* 
Generator 7 off = 1 
Generator 7 on = 0 


gendoff 

Generator 6 off = 1 
Generator 6 on = 0 

gendoff-^ 
Generator 5 off = 1 
Generator 5 on = 0 


genAoff - 
Generator 4 off = 1 
Generator 4 on = 0 

genSoff 

Generator 3 off * 1 
Generator 3 on = 0 


gen2off-^ 
Generator 2 off = 1 
Generator 2 on = 0 

genloff-^ 
Generator 1 off = 1 
Generator 1 on = 0 


genOoff 

Generator 0 off = 1 
Generator 0 on * 0 


Figure 21-6 
Stop-sound mask 
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Assembly-language example 

The following example stops generators 0 and 8; 
PEA $1001 
_StopSound 
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$0008 GetSoundVolume 

Reads the volume setting for a generator. The range of possible values is from $00 to 
$FF. All eight bits are valid for DOC volume registers. 


Parameters 

Stack before call 


Word —Space for result 

Word —^Number of generator whose volume will be returned 
<—SP 


previous contents 
wordspace 
genNumber 


Stack after call 


previous contents 
volSetting 


Word —^Volume setting, from $00 to $FF; high nibble of low-order byte 
<— SP significant 


Errors None 

C extern pascal Word GetSoundVolume(genNumber) 

Word genNumber; 
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$0B08 GetTableAddress 

Returns the jump table address for the low-level routines (see Table 21-5). 

Besides the offsets to the low-level routines, the jump table contains the following 
three additional functions: 

■ The oscillator table translates from generator number to oscillator number and 
returns the even number of the pair of oscillators. 

■ The GCB address table points to the first location of the GCB corresponding to a 
generator. 

■ The generator table translates from oscillator number to generator number. 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

<—SP 


Stack after call 


previous contents 


— jumpTableAddr — 


Long—Jump table address for low-level routines 
<—SP 


Errors None 

C extern pascal Pointer GetTableAddress() 
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Jump table addresses 

Table 21-5 illustrates the format of the jump table addresses used by the Sound Tool 
Set low-level routines. 


Table 21-5 

Jump table addresses for Sound Tool Set low-level outines 


Routine 

Offset 

Constant 


Address format 





8 bits 

8 bits 

8 bits 

8 bits 

Read Register 

$00 

readRegister 

Address low 

Address high 

Bank 

$00 

Write Register 

$04 

writeRegister 

Address low 

Address high 

Bank 

$00 

Read RAM 

$08 

readRam 

Address low 

Address high 

Bank 

$00 

Write RAM 

$0C 

writeRam 

Address low 

Address high 

Bank 

$00 

Read Next 

$10 

readNext 

Address low 

Address high 

Bank 

$00 

Write Next 

$14 

writeNext 

Address low 

Address high 

Bank 

$00 

Oscillator table 

$18 

oscTable 

Address low 

Address high 

Bank 

$00 

Generator table 

$1C 

genTable 

Address low 

Address high 

Bank 

$00 

GCB address table 

$20 

gcbAddrTable 

Address low 

Address high 

Bank 

$00 

Disable increment 

$24 

disableinc 

Address low 

Address high 

Bank 

$00 
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$0A08 


ReadRamBlock 

Reads a specified number of bytes from DCX] RAM area into system RAM. 


Warning 

Interrupts must be disabled whenever your application accesses the DOC RAM. 
Your application must disable Interrupts before it accesses the RAM and then 
reenable them afterward. 


If the number of bytes and the starting location add up to a value greater than 64K, an 
error is generated. 


Important 

Your application must call the Memory Manager to allocate the buffer for data 
read from the DOC RAM. 


Parameters 
Stack before call 
previous contents 


destPtr 


docStart 


byteCount 


Long—^POINTER to starting RAM address where data will be written 

Word—Starting DOC address from which data will be read 
Word—Number of bytes to be copied 
<— SP 


Stack after call 
previous contents 


Errors 


<— SP 

$0810 noDOCFndErr No DOC or RAM found 

$0811 docAddrRngErr DOC address range error 

extern pascal void ReadRamBlock(destPtr,docStart,byteCount) 
Pointer destPtr; 

Word docSt art; 

Word byteCount; 
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$1208 


Parameters 


SetSoundMIRQV 

Sets up the entry point into the sound interrupt handler. This routine is accessed 
every time an interrupt is generated by the DOC. 


Stack before call 
previous contents 


sMasterIRQ 


Long—New master sound IRQ vector 
<—SP 


Stack after call 
previous contents 


<— SP 


Errors 

C 


None 

extern pascal void SetSoundMIRQV(sMasterIRQ) 
LongWord sMasterIRQ; 
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$0D08 SetSoundVolume 

Changes the volume setting for the volume registers in the DOC or changes the system 
volume. 

If genNumber is specified as $00-$0E, the call sets the volume on the corresponding 
pair of generators in the DOC. If genNumber \s specified as $0F or greater, ^e call 
sets the system volume control. The range of values for the volume setting are 
$00-$FF. The generator volume registers use all eight bits of resolution. The system 
volume control uses only the upper nibble to determine the setting. 

Parameters 

Stack before call 

previous contents 
volume 
genNumber 


Word—Generator or system volume setting; $00-$FF 
Word—Generator whose volume will be set; $00-$0E sets DOC, 

<— SP $0F-$FF sets system volume 


Stack after call 

previous contents I 

|<— SP 

Errors None 

C extern pascal void SetSoundVolume(volume,genNumber) 

Word volume; 

Word genNumber; 
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$1308 SetUserSoundIRQV 

Sets up the entry point for an application-defined synthesizer interrupt handler. 
When an interrupt occurs for an application-defined synthesizer, control is passed to 
the RAM-based synthesizer code through this vector. The old vector installed is 
passed back to the caller who must preserve the vector. 

If control is passed to the user vector, the application-defined interrupt handler must 
validate that the synthesizer mode matches the synthesizer mode used by this 
handler. If it does not match, then the handler must pass control farther down the 
chain through the vector that was preserved. Control is passed through a JSL 
instruction; therefore, the application must return control through an RTL 
instruction. 


Parameters 


Stack before call 
previous contents 
longspace 


Long—Space for result 


— userIRQVector — 


Long—^New user sound IRQ vector 


^SP 


Stack after call 
previous contents 

— oldIRQVector — Long—Old user sound IRQ vector 

f- SP 

Errors None 

C extern pascal Pointer SetUserSoundlRQV(userIRQVector) 

LonqWord userIRQVector; 
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$0908 


WriteRamBlock 

Writes a specified number of bytes from system RAM into DOC RAM. 


Warning 

Interrupts must be disabled whenever your application accesses the DOC RAM. 
Your application must disable Interrupts before It accesses the RAM and then 
reenable them afterward. 


If the sum of the starting address and the byte count is greater than 64K, an error will 
be returned. 


Warning 

Do not Include the I/O space in banks $00, $01, $E0, and $E1 in the source- 
address range of bytes to be written to the DOC RAM. If you do, you will access 
soft switches that will cause the system to crash. 


Parameters 

Stack before call 
previous contents 


srcPtr 


docStart 


byteCount 


Long—POINTER to data to be written from RAM 

Word—^Starting address of DOC buffer to receive data 
Word—^Number of bytes to be written 
<—SP 


Stack after call 
previous contents 


Errors 


SP 

$0810 noDOCFndErr No DOC or RAM found 

$0811 docAddrRngErr DOC address range error 

extern pascal void WriteRamBlock(srcPtr,docStart,byteCount) 
Pointer srcPtr; 

Word docStart; 

Word byteCount; 
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(None) 

Read register 

Reads any register within the DOC. This call is made through the appropriate jump 
table address provided by a GetTableAddress call. (See the section 
“GetTableAddress” in this chapter.) The table provided by GetTableAddress 
includes a table of generator-to-oscillator translations. This table gives the number 
of the first oscillator in the pair for a generator. The number of the second oscillator 
equals the number of the first oscillator plus 1. 

By getting the oscillator number that corresponds to a particular generator and 
adding it to the base register number of a register group, an application can find out 
the settings for an oscillator. A table of the DOC registers has been provided in the 
section “Sound Hardware” in this chapter. 

This routine leaves the sound GLU in auto-increment and register access modes. 

Parameters 

The stack is not affected by this call. Instead, the following registers are used: 


Relevant registers before call 

e = 0; native mode 
m = 1; 8-bit accumulator 
X = 0; l6-bit index registers 
X = DOC register to read 

Relevant registers after call 

Accumulator (8-bit) = Contents of specified DOC register 


Errors 

None 

C 

Call cannot be made from C. 
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(None) Write register 

Writes a one-byte parameter to any register in the DOC, The call is made through the 
appropriate jump table address provided by a GetTableAddress call. To write to an 
oscillator register that corresponds to a generator, take the following steps: 

1. Take the oscillator number from the oscillator table. 

2. Add 1 to access the odd oscillator of the pair. 

3. Add the base register of the specific register. 

4. Make the Write Register call through the Write Register routine’s address in the 
jump table. 

This routine leaves the sound GLU in auto-increment and register access modes. 


Parameters 


The stack is not affected by this call. Instead, the following registers are used: 


Relevant registers before call 

e = 0; native mode 
m = 1; 8-bit accumulator 
X = 0; l6-bit index registers 
Accumulator (8-bit) = data to write 
X = DOC register number 

Relevant registers after call 

None 

Errors None 

C Call cannot be made from C. 
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(None) 


Read RAM 

Reads any specified DOC RAM location. 


Warning 

Interrupts must be disabled whenever your application accesses the DOC RAM. 
Your application must disable interrupts before It accesses the RAM and then 
reenable them afterward. 


This call is made through the appropriate jump table address provided by a 
GetTableAddress call. See the section “GetTableAddress” in this chapter. This 
routine leaves the sound GLU in auto-increment and RAM access modes. 


Important 

This routine does not do any type of error checking on the address or data. 


Parameters The stack is not affected by this call. Instead, the following registers are used: 

Relevant registers before call 

e = 0; native mode 
m = 1; 8-bit accumulator 
X = 0; l6-bit index registers 
X = DOC RAM address to read 


Relevant registers after call 

None 

Errors None 

C Call cannot be made from C. 
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(None) Write RAM 

Writes a one-byte value to any specified DOC RAM location. 


Warning 

Interrupts must be disabled whenever your application accesses the DOC RAM. 
Your application must disable interrupts before It accesses the RAM and then 
reenable them afterward. 


This call is made through the appropriate jump table address provided by a 
GetTableAddress call. See the section “GetTableAddress" in this chapter. This 
routine leaves the sound GLU in auto-increment and RAM access modes. 


Important 

This routine does not do any tyrpe of error checking on the address or data. 


Parameters The stack is not affected by this call. Instead, the following registers are used: 

Relevant registers before call 

e = 0; native mode 
m = 1; 8-bit accumulator 
X = 0; l6-bit index registers 
Accumulator (8-bit) = data to write 
X = DOC RAM address to write to 

Relevant registers after call 
None 

Errors None 

C Call cannot be made from C. 
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(None) 


Read Next 

Reads the next location pointed to by the sound GLU address register. 


Warning 

Interrupts must be disabled whenever your application accesses the DOC RAM. 
Your application must disable Interrupts before It accesses the RAM and then 
reenable them afterward. 


This call is made through the appropriate jump table address provided by a 
GetTableAddress call. 


Important 

Before making the first Read Next call in a sequertce, you must make a Read 
Register or Read RAM call with the register or address desired minus 2. This 
leaves the sound GLU control register set to auto-Increment mode and the 
sound GLU address register pointing to the correct DOC register or address. 


Parameters The stack is not affected by this call. Instead, the registers listed below are used: 


Relevant registers before call 

None (all will have been set properly by the previous Read Register or Read RAM call) 


Relevant registers after rail 
Accumulator (8-bit) = Data byte read 

Errors None 

C Call cannot be made from C. 
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(None) Write Next 

Writes one byte of data to the next DOC register or RAM location, depending on the 
setting of the sound GLU control register. 


Warning 

Interrupts must be disabled whenever your application accesses the DOC RAM. 
Your application must disable Interrupts before It accesses the RAM and then 
reenable them afterward. 


Important 

Before making the first Write Next call In a sequence, you must make a Read 
Register or Read RAM call with the register or address desired minus 2. This 
leaves the sound GLU control register set to auto-Increment mode and the 
sound GLU address register pointing to the correct DOC register or address. 


Parameters The stack is not affected by this call. Instead, the following registers are used: 


Relevant registers before call 
Accumulator (8-bit) = Data byte to write 

AH others will have been set properly by the previous Read Register or Read RAM call 

Relevant registers after call 

None 

Errors None 

C Call cannot be made from C. 
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(None) 

Disable Increment 

Disables the auto-inaement mode set up by a Read Register, Write Register, Read 
RAM, or Write RAM low-level sound routine, thus allowing your application to read a 
DOC register or memory location continuously. Auto-increment mode remains 
disabled until your application makes another Read Register, Write Register, Read 
RAM, or Write RAM call. 

For example, if you want to read the analog-to-digital converter, your application can 
make a Read Register call to Register $E2 and then make a Disable Increment call. 
Because auto-increment mode is disabled, your application can then make a Read 
Next call to read the A-to-D converter continuously. 

Pararrteters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call cannot be made from C. 
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Sound Tool Set summary 

This section briefly summarizes the constants, data structures, and tool set errors 
contained in the Sound Tool Set 


Important 

These definitions are provided In the appropriate interface file. 


Table 21-6 

Sound Tool Set constants 


Name Value Description 


Jump table offsets 

readRegister 

$00 

writeRegister 

$04 

readRam 

$08 

writeRam 

$0C 

readNext 

$10 

writeNext 

$14 

oscTable 

$18 

genTable 

$1C 

gcbAddrTable 

$20 

disableinc 

$24 

Channehgenerator-type word 

f f SynthMode 

$0001 

noteSynthMode 

$0002 

Stop-sound mask 

genOoff 

$0001 

genloff 

$0002 

gen2off 

$0004 

genSoff 

$0008 

gen4off 

$0010 

genSoff 

$0020 

gen6off 

$0040 

genVoff 

$0080 

genSoff 

$0100 

gen9off 

$0200 

genlOoff 

$0400 

genlloff 

$0800 

genl2off 

$1000 

genlSoff 

$2000 

genl4off 

$4000 


Read Register routine 
Write Register routine 
Read RAM routine 
Write RAM routine 
Read Next routine 
Write Next routine 
Pointer to oscillator table 
Pointer to generator table 
Pointer to GCB address table 
Disable Increment routine 

Free-Form Synthesizer mode 
Note Synthesizer mode 

Generator 0 off 
Generator 1 off 
Generator 2 off 
Generator 3 off 
Generator 4 off 
Generator 5 off 
Generator 6 off 
Generator 7 off 
Generator 8 off 
Generator 9 off 
Generator 10 off 
Generator 11 off 
Generator 12 off 
Generator 13 off 
Generator 14 off 
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Table 21-6 (continued) 
Sound Tool Set constants 


Name Value Description 


Generator status word 


genAvail 

$0000 

Generator available 

ffSynth 

$0100 

Free-Form Synthesizer 

noteSynth 

$0200 

Note Synthesizer 

lastBlock 

$8000 

Last block of wave 
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Sound Tool Set data structures 

Name 

Offset Type 

Definition 


SoundParamBlock (sound parameter block) 


waveStart 

$00 

Pointer 

Starting address of wave 

waveSize 

$04 

Word 

Waveform size in pages 

freqOffset 

$06 

Word 

Output sample rate 

docBuffer 

$08 

Word 

DOC buffer start address; low-order byte = 0 

bufferSize 

$0A 

Word 

DOC buffer start address; high-order byte = 0 

nextWavePtr 

$0C 

SoundPBPtr 

Pointer to start of next wave’s parameter block 

volSetting 

$10 

Word 

DOC volume setting; high-order byte = 0 


Note: The actual assembly-language equates have a lowercase letter o in front of all names 
given in this table. 


Table 21-8 

Sound Tool Set error codes 


Code Name Means 


$0810 

noDOCFndErr 

No DOC or RAM found 

$0811 

docAddrRngErr 

DOC address range error 

$0812 

noSAppInitErr 

No SoundStartUp call made 

$0813 

invalGenNumErr 

Invalid generator number 

$0814 

synthModeErr 

Synthesizer mode error 

$0815 

genBusyErr 

Generator already in use 

$0817 

mst rIRQNotAs sgnErr 

Master IRQ not assigned 

$0818 

sndAlreadyStrtErr 

Sound Tool Set already started 

$08FF 

unclaimedSndIntErr 

Unclaimed sound interrupt error 
(reported through System Failure Manager) 
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Chapter 22 


Standard File 
Operations 
Tool Set 


The Standard File Operations Tool Set provides the standard user interface for 
specify^ing a file to be opened or saved. The tool set provides dialog boxes that allow 
the user both to open and save a file on a disk in any drive and to change disks in a 
drive. 


A preview of the Standard File Operations 
Tool Set routines 

To introduce you to the capabilities of the Standard File Operations Tool Set, all of its 
routines are grouped by function and briefly described in Table 22-1. These routines 
are described in detail later in this chapter, where they are separated into 
housekeeping routines (discussed in routine number order) and the rest of the 
Standard File Operations routines (discussed in alphabetical order). 










Table 22-1 

Standard File Operations Tool Set routines and their functions 


Routine Description 


Housekeeping routines 

SFBootInit Initializes the Standard File Operations Tool Set; called only by the Tool 


SFStartUp 

SFShutDown 

SFVersion 

SFReset 

Locator—^must not be called by an application 

Starts up the Standard File Operations Tool Set for use by an application 

Shuts down the Standard File Operations Tool Set 

Returns the version number of die Standard File Operations Tool Set 

Resets the Standard File Operations Tool Set; called only when the system is 

SFStatus 

reset—^must not be called by an application 

Indicates whether the Standard File Operations Tool Set is active 


Other Standard Flie routines 

SFGetFile Displays the standard Open File dialog box and returns information about the file 


SFPutFile 

selected by the user 

Displays the standard Save File dialog box and returns information about the name 
of the file to be saved 

SFPGetFile 

Displays a custom Open File dialog box and returns information about the file 

SFPPutFile 

selected by the user 

Displays a custom Save File dialog box and returns information about the name of 
the file to be saved 

SFAllCaps 

Allows the application to decide if filenames will be displayed in all uppercase letters 
or in uppercase and lowercase letters 
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standard dialog boxes 

The standard Open File dialog box is produced by the SFGetFile routine and is 
illustrated in Figure 22-1. 


Load which Picture: 

^ /P/Tests/Hp/ 

( Oiik ) 

t- i 

[ Close ^ 

( Concel '!) 



Figure 22-1 

Standard, Open File dialog box 

The standard Save File dialog box is produced by the SFPutFile routine and is 
illustrated in Figure 22-2. 
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Figure 22-2 

Standard Save File dialog box 
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standard File dialog templates 

The Standard File Operations Tool Set allows you to provide custom dialog boxes for 
the Open File and Save File dialog boxes. To produce a custom dialog box, you use 
the SFPPutFile and SFPGetFile routines and provide a pointer to a dialog template in 
memory. A dialog template is a record passed to the Dialog Manager routine 
GetNewModalDialog, The template contains information about the dialog to be 
created, including a bounds rectangle and a list of pointers to item templates. 

The following sections provide the templates that give the standard Open File and 
Save File dialog boxes. All of the templates depend on the following strings: 


Strings 

SaveStr 

start 

str 

’Save * 


OpenStr 

str 

’open' 


CloseStr 

str 

’Close' 


DriveStr 

str 

’Next Drive* 


CancelStr 

str 

’Cancel’ 


FolderStr 

str 

’New Folder* 


KbFreeStr 

str 

’^0 free of -^1 K. 

’ ; Dialog Manager routine 


end 


/ ParamText replaces ^0 and 
; '^1 with real values from disk 


Templates for the standard Open File dialog box 

For the Open File dialog box, the item part of the template must include the following 
items in this exact order: 


Item 

Item type 

ID 

Open button 

buttonitem 

1 

Close button 

buttonitem 

2 

Next button 

buttonitem 

3 

Cancel button 

buttonitem 

4 

Scroll bar 

scrollBarltem 

5 

❖ Note: The Standard File dialog box 

only allows standard sctoU bar operations; 

it does not allow custom scroll bar routines. 

Path 

userltem 

6 

Files 

userltem 

7 

Prompt 

userltem 

8 
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640 mode 

GetDialog640 


OpenBut640 


CloseBut640 


NextBut640 


CancelBut640 


Scroll640 


Start 

using 

Strings 

dc 

i»0,0,114,400’ 

dc 

i’-l’ 

dc 

i4’0' 

dc 

i4 *OpenBut640’ 

dc 

i4’CloseBut640’ 

dc 

i4'NGXtBut640' 

dc 

i4'CancelBut640’ 

dc 

i4*Scroll640’ 

dc 

i4*Path640» 

dc 

i4*Files640' 

dc 

i4 *Prompt640 * 

dc 

i4*0’ 

dc 

i»l* 

dc 

i’53,265,65,375’ 

dc 

i’Buttonitem* 

dc 

i4’OpenStr * 

dc 

i*0* 

dc 

i*0' 

dc 

i4*0’ 

dc 

i’2* 

dc 

i'71,265,83,375’ 

dc 

i'Buttonitem' 

dc 

i4'CloseStr * 

dc 

i*0* 

dc 

i'O* 

dc 

i4'0’ 

dc 

i'3' 

dc 

i*27,265,39,375* 

dc 

i'Buttonltem* 

dc 

i4'DriveStr * 

dc 

i’O’ 

dc 

i'O’ 

dc 

i4 ’0’ 

dc 

i*4’ 

dc 

i’97,265,109,375 

dc 

i’Buttonltem’ 

dc 

i4’CancelStr’ 

dc 

i’O’ 

dc 

i'O' 

dc 

i4’0’ 

dc 

i’5’ 

dc 

i’28,214,110,238 

dc 

i* ScrollBarltem’ 

dc 

i4’0» 

dc 

i’O’ 

dc 

i’3' 

dc 

i4 *0’ 
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Path640 


Files640 


Prompt640 


320 mode 

GetDialog320 


OpenBut320 


dc 

i*6» 

dc 

1*12,49,24,395* 

dc 

i*UserItem* 

dc 

14*0* 

dc 

i*0* 

dc 

i*0* 

dc 

i4*0 

dc 

i*7* 

dc 

1*28,15,110,215* 

dc 

1*UserItem* 

dc 

14*0* 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*8* 

dc 

1*00,15,12,395* 

dc 

1 * UserItem+$8000 

dc 

14*0* 

dc 

1*0* 

dc 

1*0* 

dc 

o 

•H 

end 



start 

using 

Strings 

dc 

i'O,0,114,260' 

dc 

i'-l' 

dc 

i4'0' 

dc 

i4'OpenBut320' 

dc 

14•CloseBut320' 

dc 

14’NextBut320' 

dc 

i4'CancelBut320 

dc 

i4'Scroll320' 

dc 

i4'Path320' 

dc 

14'Files320' 

dc 

14'Prompt320' 

dc 

14 'O' 

dc 

i'l' 

dc 

i’53,160,65,255 

dc 

I'ButtonItem' 

dc 

14'OpenStr' 

dc 

I'O' 

dc 

i'O' 

dc 

14 'O' 
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CloseBut320 


NextBut320 


CancelBut320 


Scroll320 


Path320 


Files320 


Prompt320 


dc 

i*2* 

dc 

i*71,160,83,255* 

dc 

i'ButtonItem' 

dc 

14'CloseStr * 

dc 

i'O* 

dc 

i'O* 

dc 

i4'0* 

dc 

i'3' 

dc 

i'27,160,39,255' 

dc 

i'ButtonItem* 

dc 

i4*DriveStr* 

dc 

i'O* 

dc 

i'O* 

dc 

14*0' 

dc 

1 ' 4 I 

dc 

1'97,160,109,255 

dc 

1'ButtonItem* 

dc 

14'CancelStr' 

dc 

1*0* 

dc 

1*0’ 

dc 

14*0* 

dc 

1*5* 

dc 

1*27,139,109,151 

dc 

1 * ScrollBarItem* 

dc 

14*0* 

dc 

1*0* 

dc 

1*3* 

dc 

14*0* 

dc 

1*6* 

dc 

1*14,22,26,256* 

dc 

1'Userltem* 

dc 

14*0* 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*7* 

dc 

1*27,05,109,140' 

dc 

1'Userltem* 

dc 

14*0* 

dc 

1*0* 

dc 

1*0' 

dc 

o 

-H 

dc 

i'8' 

dc 

i'00,05,13,255' 

dc 

i'0serltem+$8000 

dc 

14 'O' 

dc 

i'O' 

dc 

i'O' 

dc 

14 'O' 

end 
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Templates for the standard Save File dialog box 

For the Save File dialog box, the item part of the template must include the following 
items in this exact order; 


Item 

item type 

ID 

Save button 

buttonitem 

1 

Open button 

buttonitem 

2 

Close button 

buttonitem 

3 

Next button 

buttonitem 

4 

Cancel button 

buttonitem 

5 

Scroll bar 

scrollBarltem 

6 

Path 

userltem 

7 

Files 

userltem 

8 

Prompt 

userltem 

9 

Filename 

editItem 

10 

Free space 

statText 

11 

Create button 

button 

12 


640 mode 



PutDialog640 

start 

using 

Strings 


dc 

i*0,0, 120,320' 


dc 

i'-l' 


dc 

i4 *0' 


dc 

i4•SaveButP640' 


dc 

i4'OpenButP640' 


dc 

i4'CloseButP640' 


dc 

i4 »NextButP640* 


dc 

i4'CancelButP640 


dc 

i4'ScrollP640* 


dc 

i4'PathP640' 


dc 

i4'FilesP640* 


dc 

i4 *PromptP640' 


dc 

i4 *EditP640' 


dc 

i4•StatTextP640* 


dc 

i4*CreateButP640 


dc 

i4 *0* 

SaveButP640 

dc 

i'l' 


dc 

i'87,204,99,310* 


dc 

i'Buttonitem■ 


dc 

i4'SaveStr• 


dc 

i'O' 


dc 

i'O' 


dc 

i4'0* 
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OpenButP640 


CloseButP640 


NextButP640 


CancelButP640 


ScrollP640 


PathP640 


FilesP640 


dc 

i*2* 

dc 

1*49,204,61,310 

dc 

i*ButtonItem* 

dc 

14'OpenStr * 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*3* 

dc 

1*64,204,76,310 

dc 

1 * ButtonItem* 

dc 

14 *CloseStr * 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*4 * 

dc 

1*15,204,27,310 

dc 

l*ButtonItem* 

dc 

14'DriveStr * 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*5* 

dc 

1*104,204, 116,3: 

dc 

l*ButtonItem* 

dc 

14 *CancelStr * 

dc 

1*0* 

dc 

1*0* 

dc 

o 

•H 

dc 

1*6* 

dc 

1*26,169,88,194 

dc 

1'ScrollBarltem 

dc 

14*0* 

dc 

1*0* 

dc 

1*3* 

dc 

14*0* 

dc 

1*7* 

dc 

1*00,10,12,315* 

dc 

1'Userltem* 

dc 

14*0* 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*8* 

dc 

1*26,10,88,170* 

dc 

1 * Userltem* 

dc 

14*0* 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 
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Prompt?640 


EditP640 


StatTextP640 


CreateButP640 


320 mode 

PutDlalog320 


dc 

i'9' 

dc 

i’88,10,100,200' 

dc 

i'UserItero+$8000 

dc 

i4'0' 

dc 

i'O* 

dc 

i'O' 

dc 

14 'O' 

dc 

i'lO' 

dc 

i'lOO,10,118,194 

dc 

i'EditLine' 

dc 

i4'00' 

dc 

i'15' 

dc 

i'O' 

dc 

i4'0' 

dc 

i'll' 

dc 

i'12,10,22,200' 

dc 

i'StatText+$8000 

dc 

i4'KbFreeStr' 

dc 

i'O' 

dc 

i'O' 

dc 

i4'0' 

dc 

i'12' 

dc 

i'29,204,41,310' 

dc 

i'Buttonitem' 

dc 

14'FolderStr' 

dc 

i'O' 

dc 

i'O' 

dc 

i4'0' 

end 



Start 

using 

Strings 

dc 

i*0,0,128,270* 

dc 

i'-l* 

dc 

i4»0* 

dc 

i4*SaveButP320* 

dc 

i4»OpenButP320* 

dc 

i4 *CloseButP320* 

dc 

i4*NextButP320’ 

dc 

i4 *CancelButP320 

dc 

i4*ScrollP320* 

dc 

i4*PathP320» 

dc 

i4»FilesP320* 

dc 

i4*PromptP320* 

dc 

i4*EditP320* 

dc 

i4•StatTextP320* 

dc 

i4 *CreateButP320 

dc 

i4*0* 
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SaveButP320 


OpenButP320 


CloseButP320 


NextButP320 


CancelButP320 


ScrollP320 


dc 


dc 

i»93,165,105,265* 

dc 

i*ButtonItem* 

dc 

i4'SaveStr* 

dc 

i’O' 

dc 

i'O* 

dc 

14*0* 

dc 

i'2* 

dc 

1*54,165,66,265* 

dc 

1*ButtonItem' 

dc 

14'OpenStr’ 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*3* 

dc 

1*72,165,84,265* 

dc 

1*ButtonItem* 

dc 

14 *CloseStr' 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*4* 

dc 

1*15,165,27,265* 

dc 

1 * ButtonItem* 

dc 

14 *DrlveStr* 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*5* 

dc 

1*111,165,123,265 

dc 

1 * Buttonitem' 

dc 

14 *CancelStr* 

dc 

1*0* 

dc 

1*0* 

dc 

14*0* 

dc 

1*6* 

dc 

1*26,144,88,157* 

dc 

1 * ScrollBarltem* 

dc 

14*0’ 

dc 

1*0* 

dc 

1*3* 

dc 

14*0* 
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PathP320 


dc i* 7 * 

dc i'00,10,12,265* 

dc i’Userltem' 

dc i4*0' 

dc i* 0 * 

dc i* 0 * 

dc i4*0* 

FilesP320 dc i'8» 

dc 1*26,10,88,145* 

dc i*UserItem' 

dc 14*0* 

dc i'0 * 

dc 1*0* 

dc 14*0* 

PromptP320 dc 1*9* 

dc 1*88,10,100,170* 

dc l*UserItem+$8000» 

dc 14*0* 

dc 1 * 0 * 

dc 1 * 0 * 

dc 14*0* 

EdltP320 dc 1*10* 

dc 1*100,10,118,157* 

dc l*EdltLlne' 

dc l4*TltleWln* 

dc 1*15* 

dc 1*0* 

dc 14*0* 

StatTextP320 dc 1*11* 

dc 1*12,10,22,160* 

dc 1 * StatText+$8000 * 

dc 14*KbFreeStr* 

dc 1 * 0 * 

dc 1 * 0 * 

dc 14*0* 

CreateButP320 dc 1*12* 

dc 1*33,165,45,265* 

dc 1 * ButtonItem* 

dc 14 *FolderStr* 

dc 1 * 0 * 

dc 1 * 0 * 

dc 14*0* 

See Chapter 6, “Dialog Manager,” in Volume 1 for further details. 

The bounding rectangle for the Files user item determines how many files may be 
displayed at one time. You should set the height of this rectangle to 2 plus 10 times 
the number of files to show. A height of 122 would allow 12 files to be seen. 
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Using the Standard File Operations Tool Set 

This section discusses how the Standard File Operations Tool Set routines fit into the 
general flow of an application and gives you an idea of which routines youll need to 
use under normal circumstances. Each routine is described in detail later in this 
chapter. 

The Standard File Operations Tool Set depends on the presence of the tool sets 
shown in Table 22-2 and requires that at least the indicated version of each tool set be 
present. 


Table 22-2 

Standard File Operations Tool Set—other tool sets required 


Tool set 
number 

Tool set 
name 

Minimum version 
needed 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$04 

#04 

QuickDraw n 

1.0 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

$10 

#16 

Control Manager 

1.3 

$0F 

#15 

Menu Manager 

1.3 

$14 

#20 

LineEdit Tool Set 

1.0 

$15 

#21 

Dialog Manager 

1.1 


To use the Standard File Operations Tool Set routines, your application must call the 
SFStartUp routine before making any other Standard File calls. To save memory 
space, you can choose to have your application make the SFStartUp call only when it 
needs to present the dialog boxes. Use the LoadOneTool routine in the Tool Locator 
if you wish to use this method. See the section “SFStartUp” in this chapter for an 
example. 

Use the SFShutDown routine to shut down the Standard File Operations Tool Set after 
you have finished using it. If you wish, you can unload the tool set with the Tool 
Locator routine UnLoadOneTool, which will unload the tool set from memory and 
thus save space. 


Important 

If you choose to unload the Standard File Operations Tool Set, be sure to reload 
It with a LoadOneTool call before making the SFStartUp call again. 
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When the user makes a request to open a file, use the SFGetFile routine in your 
application to present the standard Open File dialog box and retrieve the file name. 
SFGetFile allows you to speciiy where the standard dialog box will be placed on the 
screen, specify the prompt at the top of the box, and filter the type of files to be 
displayed in the box. The routine does not allow you to modify the appearance of 
the box; if you wish to construct your own custom dialog box, use the SFPGetFile 
routine. 

When the user makes a request to save a file, use the SFPutFile routine to present the 
standard dialog Save File dialog box. SFPutFile allows you to specify where the 
standard dialog box will be placed on the screen, the prompt at the top of the box, 
and the maximum number of characters the user may type. 

Like SFGetFile, SFPutFile does not allow you to modify the appearance of the box; if 
you wish to constmct your own custom dialog box, use the SFPPutFile routine. 
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$0117 


SFBootInit 

Initializes Standard File Operations Tool Set; called only by the Tool Locator. 



Warning 

An application must never make this call. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call must not be made by an application. 
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$0217 


SFSiartUp 

Starts up the Standard File Operations Tool Set for use by an application. 


Important 

Your application must make this call before It makes any other Standard File 
calls. 


You may choose to have your application call SFStartUp only when it is needed, thus 
freeing memory for other uses. The number of the Standard File Operations Tool Set 
is $17, so a typical sequence of calls (in a pseudocode format) might be 

LoadOneTool ($17,$0101) 

SFStartUp (appropriate parameters) 

SFGetFile (appropriate parameters) 

SFShutDown 
UnloadOneTool ($17) 


Parameters 

Stack before call 


Word—ID number of application 

Word—Bank $0 starting address for one page of direct-page space 
4- SP 


previous contents 
userlD 
dPageAddr 


Stack after call 
I previous contents 


4- SP 


Errors None 


C extern pascal void SFStartUp{userlD,dPageAddr) 

Word userlD; 

Word dPageAddr/ 
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$0317 

SFShutDown 

Shuts down the Standard File Operations Tool Set. Your application may call 
SFShutDown immediately after Standard File Operations are completed, thus freeing 
memory for other uses. 

Parameters 

Important 

If your application has started up Standard File Operations, the application must 
make this call before it quits. 

The number of the Standard File Operations Tool Set is $17, so a typical sequence of 
calls (in a pseudocode format) might be 

LoadOneTool ($17,$0101) 

SFStartUp (appropriate parameters) 

SFGetFile (appropriate parameters) 

SFShutDown 

UnloadOneTool ($17) 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void SFShutDown() 
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$0417 SFVersion 

Returns the version number of the Standard File Operations Tool Set. 

Parameters 

Stack before call 

previous contents 
wordspace 

Stack after call 
previous contents 

versionlnfo Word—^Version number of Standard File Operations Tool Set 

<—SP 

Errors None 

C extern pascal Word SFVersion() 


Word—Space for result 
<— SP 


$0517 SFReset 

Resets the Standard File Operations Tool Set; called only when the system is reset. 
Warning 

An application must never make this call. 

Parameters The stack is not affected by this call. There are no input or output parameters. 

Errors None 

C Call must not be made by an application. 
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$0617 SFStatus 

Indicates whether the Standard File Operations Tool Set is active. 

SFStatus returns TRUE if SFStartUp has been called and SFShutDown has not been 
called. The routine returns FALSE if SFStartUp has not been called at all or if 
SFShutDown has been called since the last time SFStartUp was called. 


Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

SP 


Stack after call 
previous contents 

activeFlag Word— BOOLEAN; TRUE if Standard File active, FALSE if inactive 

SP 

Errors None 

C extern pascal Boolean SFStatus() 
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$0D17 SFAIICaps 

Mows an application to decide if filenames will be displayed in all uppercase letters 
or in uppercase and lowercase letters. If allCapsFlag is set to FALSE, the initial letter 
of the Rename will be uppercase and the first letter after a period will be uppercase; 
all other letters will be lowercase. 


Parameters 

Stack before call 
previous contents 

allCapsFlag Word—BOOLEAN; TRUE for uppercase filenames, FALSE for mixed 

<—SP 


Stack after call 

( previous contents I 

<— SP 


Errors None 

C extern pascal void SFAllCaps(allCapsFlag) 

Boolean allCapsFlag; 
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$0917 SFGetFile 

Displays the standard Open File dialog box and returns information about the file 
selected by the user. 

Parameters 


Stack before call 
previous contents 


whereX 


whereY 


promptPtr 


— filterProcPtr 


typeListPtr 


replyPtr 


Word —INTEGER; X coordinate of upper left corner of dialog box 
Word —INTEGER; Y coordinate of upper left corner of dialog box 

Long —POINTER to string to display at top of dialog box 

Long —POINTER to filter procedure; NIL for none 

Long —POINTER to typelist record; NIL to display all files 

Long —POINTER to a reply record 
<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SFGetFile(whereX,whereY,promptPtr, 

filterProcPtr,typeListPtr,replyPtr) 

Integer whereX; 

Integer whereY; 

Pointer promptPtr; 

WordProcPtr filterProcPtr; 

Pointer typeListPtr; 

SFReplyRecPtr replyPtr; 
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You can also use the following alternate form of the call: 

extern pascal void SFGetFile(where,promptPtr, 
filterProcPtr,typeListPtr,replyPtr) 

Point where; 

Pointer promptPtr; 

WordProcPtr filterProcPtr; 

Pointer typeListPtr; 

SFReplyRecPtr replyPtr; 


More about parameters 

The filter procedure pointed to by filterProcPtr determines which files will be 
displayed in the dialog box. Set filterProcPtr to NIL to prevent the procedure from 
being called. The filter procedure is called in full native mode, in the same way as 
one would call a Pascal function having one long parameter. 

The calling sequence inside SFGetFile is as follows: 

PushWord #0 ; Space for result 

PushLong #DirEntry ; Pointer to directory entry ($27 bytes long) 
jsl FilterProc 
PopWord Result 

The procedure must strip the four bytes of the directory entry off the stack and return 
with the result at the top of the stack. The result indicates what the procedure wants to 
do with the file, as shown in Table 22-3. 

Table 22-3 

Filter procedure results 


Value Name Description 

0 noDisplay Don’t display file 

1 noSelect Display file but don’t allow user to select the file 

2 displaySelect Display file and allow user to select the file 

The directory entry for the file is illustrated in Figure 22-3. 
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Offset 


storagejype 

namejengfh 

— 

— 


1 

2 


OF 

10 

11 

12 

flle_name 

— 

fHe_type 

— keyjx>lnter 

— 

13 

— blocks used 


14 



15 



16 

EOF 


17 



18 



19 

creation 


— date and time 

— 

lA 



IB 



1C 

version 

ID 

mln_verslon 

IE 

access 

IF 




— aux^type 

— 

20 



21 



22 

_ modification 


23 

date and time 


24 



25 

— headerjoointer 


26 




Figure 22-3 

File directory entry 


Field 
1 byte 


15 bytes 

1 byte 

2 bytes 

2 bytes 

3 bytes 

4 bytes 

1 byte 
1 byte 

1 byte 

2 bytes 

4 bytes 

2 bytes 


For more information on the fields of the directory entry, see the Apple IIGS 
ProDOS 16 Reference, 

The typeListPtr pditzmQXQt points to a record containing a list of file types to display 
(set the pointer to NIL to display all file types). The list has the form shown in 
Figure 22-4. 



Byte— Total number of entries In list 
Byte— First file type to display 
Byte— Second file type to display 


Byte— Last file type to display 


Figure 22-4 
Typellst record 


(continued) 
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If you specify both a filterProcPtr znA a typeListPtr, only files of the right file type or 
types are passed on to the filterProc procedure. 

The replyPtr parameter points to a reply record that has the form shown in 
Figure 22-5. 


Offset Field 



Word-BOOLEAN; TRUE for open. FALSE for cancel 
Word—ProDOS file type 
Word—ProDOS auxiliary file type 

16 bytes—Name of file In prefix 0 


129 bytes—Full pathname of file in prefix 0 


Figure 22-5 
Reply record 

When the dialog box is displayed, the files from prefix 0 are shown. When the file is 
selected, the name of the file is returned in the record pointed to by replyPtr z,nd 
prefix 0 is set to the directory containing the selected file. If the user cancels the 
operation, prefix 0 is left at whatever direaory is being shown at the time. 

❖ Macintosh programmers: The Disk button works differently from the Drive 
button in the Macintosh, When a user clicks on the Disk button. Standard File 
first looks at the disk in the drive the current disk is expected to be in. If the 
current disk is no longer in that drive, the disk in that drive becomes the current 
disk. If the current disk is still there, the Disk button moves to the next disk in the 
ProDOS chain. The Disk button works this way because a user can change disks 
without the system knowing about it. 
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$0B17 SFPGetFiie 

Displays a custom Open File dialog box and returns information about the file 
selected by the user. 


Parameters 

stack before call 

Word—INTEGER; X coordinate of upper left corner of dialog box 
Word—INTEGER; Y coordinate of upper left comer of dialog box 

Long—POINTER to string to display at top of dialog box 
Long—POINTER to filter procedure; NIL for none 
Long—POINTER to a typelist record; NIL to display all files 
Long—POINTER to a dialog template in memory 

Long—POINTER to a routine called every time ModalDialog returns a hit 

Long—POINTER to a reply record 
4- SP 


previous contents 
whereX 
whereY 


promptPtr 


— filterProcPtr — 


— typeListPtr 


dlgTempPtr 


— dialogHookPtr — 


replyPtr 


Stack after call 
previous contents 


4- SP 


Errors None 


C extern pascal void SFPGetFiie(whereX,whereY,promptPtr,filterProcPtr, 

typeListPtr,dlgTempPtr,dialogHookPtr,replyPt r) 

Integer whereX; 

Integer whereY; 

Pointer promptPtr; 

WordProcPtr filterProcPtr; 

Pointer typeListPtr; 

DlgTempPtr dlgTempPtr; 
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VoidProcPtr 


dialogHookPtr; 
replyPtr; 


SFReplyRecPtr 


The dIgTempPtr and dialogHookPtr parameters 

SFPGetFile works like SFGetFile, except for the addition of the dlgTempPtrdSid 
dialogHookPtr parameters. The dlgTempPtr provides a pointer to a dialog 
template; the template is a record passed to the Dialog Manager routine 
GetNewModalDialog. The template contains information about the dialog to be 
created, including a bounds rectangle and a list of pointers to item templates. 

For the Open File dialog box, the item part of the template must include the following 


items in this exact order: 

Item Item type ID 

Open button buttonitem 1 

Close button buttonitem 2 

Next button buttonitem 3 

Cancel button buttonitem 4 


Scroll bar scrollbarltem 5 

❖ Note: The Standard File dialog box only allows standard scroll bar operations; 
it does not allow custom scroll bar routines. 

Path userltem 6 

Files userltem 7 

Prompt userltem 8 

For more information and examples of dialog templates, see the section “Standard 
File Dialog Templates” in this chapter. 

The dialogHookPtr parameter is a pointer to the routine called by SFPGetFile every 
time ModalDialog returns an item hit. The routine is passed a pointer to the dialog 
port and a pointer to the item-hit word. If the dialogHook routine wants to handle 
the item hit, it should handle it and set the hit to 0. If it wants SFPGetFile to handle 
the item hit, it should leave it unchanged. 

The routine is called as follows: 

PushLong #DialogPort 
PushLong #ItemHit 
jsl DialogHook 
Ida ItemHit 

Your routine must be certain to strip the two longs (eight bytes) representing the 
DialogPort and ItemHit pointers off the stack before returning to SFPGetFile. 
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$0C17 SFPPutFile 

Displays a custom Save File dialog box and returns information about the name of the 
file to be saved. 

Parameters 


Stack before call 

previous contents 
whereX 
whereY 

promptPtr 


Word—INTEGER; X coordinate of upper left corner of dialog box 
Word—INTEGER; Y coordinate of upper left comer of dialog box 

Long—POINTER to string to display at top of dialog box 


— origNamePtr 


maxLen 


dlgTempPtr 


— dialogHookPtr — 


replyPtr 


Long—POINTER to string holding name that appears as default 
Word—INTEGER; maximum number of characters user may type 
Long—POINTER to a dialog template in memory 

Long—POINTER to a routine called every time ModalDialog returns a hit 

Long—POINTER to a reply record 
SP 


Stack after call 


previous contents 


SP 


Errors None 


Standard File Operations Tool Set routines 22-27 


















c 


extern pascal void SFPPutFile(whereX,whereY,promptPtr,origNamePtr,maxLen, 
dlgTempPtr,dialogHookPtr,replyPtr) 


Integer whereX; 

Integer whereY; 


Pointer 

promptPtr; 

Pointer 

origNamePtr; 


unsigned int maxLen; 

DlgTempPtr dlgTempPtr; 

VoidProcPtr dialogHookPtr; 

SFReplyRecPtr replyPtr; 

You can also use the following alternate form of the call: 

extern pascal void SFPPutFile(where,promptPtr,origNamePtr,maxLen,dlgTempPtr, 
dialogHookPtr,replyPtr) 

Point where; 


Pointer 

promptPtr; 

Pointer 

origNamePtr; 


unsigned int maxLen; 
DlgTempPtr dlgTempPtr; 

VoidProcPtr dialogHookPtr; 

SFReplyRecPtr replyPtr; 
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The dIgTempPtr and diaiogHookPtr parameters 

This routine works like SFPutFile, except for the addition of the dlgTempPtr and 
diaiogHookPtr parameters. The dlgTempPtr provides a pointer to a dialog 
template; the template is a record passed to the Dialog Manager routine 
GetNewModalDialog. The template contains information about the dialog to be 
created, including a bounds rectangle and a list of pointers to item templates. 

The item part of the template must include the following items in this exact order*. 


Item 

Item type 

ID 

Save button 

buttonitem 

1 

Open button 

buttonitem 

2 

Close button 

buttonitem 

3 

Next button 

buttonitem 

4 

Cancel button 

buttonitem 

5 

Scroll bar 

scrollBarltem 

6 

Path 

userltem 

7 

Files 

userltem 

8 

Prompt 

userltem 

9 

Filename 

edititem 

10 

Free space 

statText 

11 

Create button 

button 

12 


For more information and examples of dialog templates, see the section “Standard 
File Dialog Templates” in this chapter and Chapter 6, “Dialog Manager,” in 
Volume 1 for further details. 

The bounding rectangle for the Files user item determines how many files may be 
displayed. You should set the height of this rectangle to 2 plus 10 times the number 
of files to show at one time. A height of 122 would allow 12 files to be seen at one 
time. 

The diaiogHookPtr parameter is a pointer to the routine called by SFPPutFile every 
time ModalDialog returns an item hit. The routine is passed a pointer to the dialog 
port and a pointer to the item-hit word. If the DialogHook routine wants to handle 
the item hit, it should handle it and set the hit to 0. If the DialogHook routine wants 
SFPPutFile to handle the item hit, it should leave the hit unchanged. 

The routine is called as follows in assembly language: 

PushLong #DialogPort 
PushLong #ItemHit 
jsl DialogHook 
Ida ItemHit 

Your routine must be certain to strip the two longs (eight bytes) representing the 
DialogPort and the ItemHit off the stack before returning to SFPPutFile. 
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$0A17 SFPutFile 

Displays the standard Save File dialog box and returns information about the name of 
the file to be saved. 

Parameters 

Stack before call 

previous contents 
whereX 
whereY 

promptPtr 

— origNamePtr — 

maxLen 

— replyPtr — 


Word —INTEGER; X coordinate of upper left comer of dialog box 
Word —^INTEGER; Y coordinate of upper left comer of dialog box 

Long —POINTER to string to display at top of dialog box 

Long —POINTER to string holding name that appears as default 
Word —INTEGER; maximum number of characters user may type 
Long —POINTER to a reply record 
<—SP 


Stack after call 
previous contents 

|<— SP 

Errors None 

C extern pascal void SFPutFile<whereX,whereY, promptPtr, 

origNamePtr,maxLen,replyPtr) 

Integer whereX; 

Integer whereY; 

Pointer promptPtr; 

Pointer origNamePtr; 
unsigned int maxLen; 

SFReplyRecPtr replyPtr; 
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You can also use the following alternate form of the call: 

extern pascal void SFPutFile(where,promptPtr,origNamePtr,maxLen,replyPtr) 


Point where; 

Pointer promptPtr; 
Pointer origNamePtr; 
unsigned int maxLen; 
SFReplyRecPt r replyPt r; 


More about parameters 

The maxLen parameter specifies the maximum number of characters a user may 
type. Most applications will use 15 for this value, but if the application wants to add a 
suffix to the file name, the maxLen value must be shortened. Values greater than 15 
are not valid. 

The replyPtrpo\xiXs to the same type of reply record as that of SFGetFile. See 
Figure 22-5 in the section “SFGetFile” in this chapter. 

When the dialog box is first displayed, all the files from prefix 0 are shown. This lets 
the user know what names are in use and prevents use of a name that already exists. 

The user can open any directories shown as selectable; files not shown as selectable 
cannot be opened. When the user clicks on the Save button or presses the Return 
key, the name of the file is returned in the reply record and prefix 0 is set to the 
directory containing the selected file. If the user cancels the operation, prefix 0 is 
restored to its original state. 

SFPutFile also checks to see if the file already exists. If it does, SFPutFile displays a 
dialog asking if is OK to destroy the existing file. 

If the user cancels the operation, prefix 0 is left at whatever directory is being shown 
at the time. 

❖ Macintosh programmers: The Disk button works differently from the Drive button 
in the Macintosh. When a user clicks on the Disk button, Standard File first looks at 
the disk in the drive the current disk is expected to be in. If the current disk is no 
longer in that drive, the disk in that drive becomes the current disk. If the current 
disk is still there, the Disk button moves to the next disk in the ProDOS chain. The 
Disk button works this way because a user can change disks without the system 
knowing about it. 
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standard File Operations Tool Set summary 

This section briefly summarizes the constants and data structures contained in the 
Standard File Operations Tool Set. There are no tool set error codes for the Standard 
File Operations Tool Set. 


Important 

These definitions ore provided In the appropriate Interface file. 


Table 22-4 

Standard File Operations Tool Set constants 


Name Value Description 


Filter procedure results 

noDisplay $0000 Don’t display file 

noSelect $0001 Display file, but don’t allow user to select it 

displaySelect $0002 Display file and allow user to select it 

Table 22-5 

Standard File Operations Tool Set data structures 


Name Offset Type Definition 


Reply record 
good 

$00 

Boolean 

fileType 

$02 

Word 

auxFileType 

$04 

Word 

fileName 

$06 

l6 bytes 

fullPathname 

$16 

129 bytes 


TRUE for Open, FALSE for Cancel 
ProDOS file type 
ProDOS aux file type 
Name of the file in prefix .0 
Full pathname of selected file 


Note: The actual assembly-language equates have a lowercase letter o in front of all of the 
names given in this table. 
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Chapter 23 


Text Tool Set 


The Text Tool Set provides an interface between Apple II character device drivers, 
which must be executed in emulation mode, and new applications running in native 
mode. It also provides a means of redirection of I/O through RAM-based drivers. 
The Text Tool Set makes it possible to deal with the text screen without switching 
65816 processor modes and moving to bank zero. Dispatches to RAM-based drivers 
will occur in full native mode. 


A preview of the Text Tool Set routines 

To introduce you to the capabilities of the Text Tool Set, all of its routines are 
grouped by function and briefly described in Table 23-1. These routines are 
described in detail later in this chapter, where they are separated into housekeeping 
routines (discussed in routine number order) and the rest of the Text Tool Set 
routines (discussed in alphabetical order). 

Table 23-1 

Text Tool Set routines and their functions 


Routine Description 


Housekeeping routines 


TextBootInit 

TextStartUp 

TextShutDown 

TextVersion 

TextReset 

TextStatus 


Initializes the Text Tool Set; called only by the Tool Locator—^must not be called by 
an application 

Starts up the Text Tool Set for use by an application 
Shuts down the Text Tool Set when an application quits 
Returns the version number of the Text Tool Set 

Resets the Text Tool Set; called only when the system is reset—^must not be called by 
an application 

Indicates whether the Text Tool Set is active 


(continued) 









Table 23-1 (continued) 

Text Tool Set routines and their functions 


Routine Description 


Text global functions 
SetInGlobals Sets the 

SetOutGlobals Sets the 

SetErrGlobals Sets the 

GetInGlobals Returns 

GetOutGlobals Returns 

GetErrGlobals Returns 

I/O directing routines 
SetInputDevice Sets the 

SetOutputDevice Sets the 

SetErrorDevice Sets the 

GetInputDevice Returns 

GetOutputDevice Returns 

GetErrorDevice Returns 


global parameters for the input device 

global parameters for the output device 

global parameters for the error output device 

the current values for the input device global parameters 

the current values for the output device global parameters 

the current values for the error output device global parameters 

input device to a specified type and location 
output device to a specified type and location 
error output device to a specified type and location 
the type of driver installed as the input device 
the type of driver installed as the output device 
the type of driver installed as the error output device 


Text routines 

InitTextDev 

CtlTextDev 

StatusTextDev 

WriteChar 

ErrWriteChar 

WriteLine 


ErrWriteLine 

WriteString 

ErrWriteString 

TextWriteBlock 

ErrWriteBlock 

WriteCString 

ErrWriteCString 


Initializes a specified text device 

Passes a control code to a specified text device 

Executes a status call to a specified text device 

Combines a specified character with the output global AND mask and OR mask and 
writes the character to the output text device 

Combines a specified character with the output global AND mask and OR mask and 
writes the character to the error output text device 

Combines a pointed-to Pascal-type string (first byte of string specifies length) with 
the output global masks, concatenates a carriage return (for BASIC or RAM-based 
drivers) or a carriage return and line feed (for Pascal drivers), and then writes the 
string to the output text device 

Combines a pointed-to Pascal-type string (first byte of string specifies length) with 
the output global masks and then writes the string to the error output text device 
Combines a pointed-to Pascal-type string (first byte of string specifies length) with 
the output global masks and then writes the string to the output text device 
Combines a pointed-to Pascal-type string (first byte of string specifies length) with 
the output global masks and then writes the string to the error output text device 
Combines a specified character string with the output global masks and then writes 
the string to the output text device 

Combines a specified character string with the output global masks and then writes 
the string to the error output text device 

Combines a pointed-to C string (string terminates with $00) with the output global 
masks and then writes the string to the output text device 

Combines a pointed-to C string (string terminates with $00) with the output global 
masks and then writes the string to the error output text device 
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Table 23-1 (continued) 

Text Tool Set routines and their functions 


Routine Description 


ReadChar 

ReadLine 

TextReadBlock 


Reads a character obtained from the input text device, combines it with the input 
global masks, and returns the character on the stack 

Reads a character string from the input text device, combines it with the input global 
masks, and writes the string to a specified memory location 
Reads a block of characters from the input text device, combines it with the input 
global masks, and writes the block to a specified memory location 


Using the I/O directing routines 

The I/O directing routines direct I/O from the Text Tool Set to a specific type of 
character device driver or get information about the directing of a specific I/O 
driver. The types of character device drivers are listed in Table 23-2. 

Table 23-2 

Character device driver types 
Type Description 


0 BASIC device driver 

1 Pascal device driver 

2 RAM-based device driver 

>3 Illegal driver type 


BASIC device drivers must support the standard Apple II BASIC device driver entry 
points (INIT, INPUT, and OUTPUT). 

❖ Note: BASIC devices use the Apple II I/O hooks ($36-$39) in absolute zero 
page. 

Any desk accessories using a Text Tool BASIC device driver should save and restore 
the global masks, device descriptors, and I/O hooks when entering or leaving the 
desk accessory. 

Pascal device drivers must support the standard Apple II Pascal 1.1 device driver 
entry points (INIT, READ, WRITE, and status). The optional Pascal 1.1 control entry 
point is supported by the Text Tool Set but does not necessarily have to be supported 
by the device. The application must find out if the device supports the optional 
Pascal entry points. 
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RAM-based device drivers may be located at any address and in any bank. A RAM- 
based driver must support five entry points, as follows: 


RAMDRIVER Base Address 
RAMDRIVER Base Address + 3 
RAMDRIVER Base Address + 6 
RAMDRIVER Base Address + 9 
RAMDRIVER Base Address + 12 


INIT (initialization) entry point 
READ entry point 
WRITE entry point 
STATUS entry point 
CONTROL entry point 


RAM-based drivers are called by the Text Tool Set in native mode (m and x bits set to 
l6 bits) and should return to the Text Tools via an RTL instruction. The Text Tools 
pass data or ASCII characters to the RAM-based driver via the low-order byte of the 
l6-bit accumulator. 


A RAM-based driver should not make any assumptions about the state of the data 
bank register or the direct page register. I/O performed by RAM-based drivers 
should operate on a single-character basis. The Text Tool Set, not the RAM-based 
driver, manipulates the text with regard to the global masks before passing the text to 
the RAM-based driver. All Text Tool Set routines that interface to different string 
types are supported by the tool set and not the device. 


Using the text routines 

The following example demonstrates how to set up global parameters, initialize the 
text devices, send output to the error and output devices, and read input from the 
input device. 


list 

on 

instime 

off 

absaddr 

on 

gen 

off 

symbol 

off 

keep 

testit 

65816 

on 

msb 

on 

mcopy 

mm.macros 

mcopy 

misc.macros 

mcopy 

tt.macros 

test 

start 
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C2 30 


NoErrO 


NoErrl 


NoErr2 


NoErr3 


rep 

#$30 


longa 

on 


longi 

on 


_TextStartUp 



bcc 

NoErrO 

; If no error 

jmp 

ToolError 

; else 

anop 



pea 

$00FF 

; AND mask 

pea 

$0080 

; OR mask 

_SetInGlobals 



bcc 

NoErrl 

/ If no error 

jmp 

ToolError 

/ else 

anop 



pea 

$00FF 

/ AND mask 

pea 

$0080 

; OR mask 

_SetOutGlobals 


bcc 

NoErr2 

/ If no error 

jmp 

ToolError 

; else 

anop 



pea 

$00FF 

/ AND mask 

pea 

$0080 

; OR mask 

_SetErrGlobals 


bcc 

NoErr3 

; If no error 

jmp 

ToolError 

; else 

anop 



pea 

$0000 

; 0 = basic driver 

pea 

$0000 

; in slot #3 

pea 

$0003 

r 

_SetInputDevice 


bcc 

NoErr4 

; If no error 

jmp 

ToolError 

/ else 
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NoErr4 


anop 



pea 

$0000 

f 

0 = basic driver 



pea 

$0000 

t 

in slot #3 



pea 

$0003 

f 




_SetOutputDevice 





bcc 

NoErrS 

r 

If no error 



jmp 

ToolError 

t 

else 


NoErrS 

anop 






pea 

$0000 

/ 

0 = basic driver 



pea 

$0000 

! 

in slot #1 



pea 

$0001 

f 




_SetErrorDevice 





bcc 

NoErr6 

/ 

If no error 



jmp 

ToolError 

r 

else 


NoErr6 

anop 






pea 

$0000 

i 

Initialize the input 

device 


_InitTextDev 






bcc 

NoErr? 

t 

If no error 



jmp 

ToolError 

r 

else 


NoErr7 

anop 






pea 

$0001 

t 

Initialize the output 

device 


_InitTextDev 






bcc 

NoErrS 

f 

If no error 



jmp 

ToolError 

f 

else 


NoErrS 

anop 






pea 

$0002 

? 

Initialize the error 

device 


_InitTextDev 






bcc 

NoErr9 

r 

If no error 



jmp 

ToolError 

r 

else 
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NoErr9 


anop 



pha 



pea 

$0000 


_ReadChar 



bcc 

NoErrlO 


jmp 

ToolError 

NoErrlO 

anop 



pushlong 

fbuffer 


pea 

$0080 


pea 

$0100 


pea 

$0001 


_ReadBlock 



bcc 

NoErrll 


jmp 

ToolError 

NoErrll 

anop 



pushlong 

#outstring 


_WriteCString 



bcc 

NoErrl2 


jmp 

ToolError 

NoErrl2 

anop 



pushlong 

tErrString 


_ErrWriteCString 


bcc 

NoErrl3 


jmp 

ToolError 

NoErrlS 

anop 



rts 



Space for result 
Don’t echo 
Wait for any key 
If no error 
else 

Pointer to input buffer 

Offset into buffer 

256 characters is max block size 

Echo characters to output device 

Wait for any key 

If no error 

else 

Pointer to the output device string 
and send it out 
If no error 
else 

Pointer to the error device string 
and send it out 
If no error 
else 
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ToolError 


FallMsg 


an Op 



pha 


; Error code for display 

pushlong 

#FailMsg 

; Pointer to error message 

_SysFailMgr 



outstring 

anop 


dc 

c'This string 

should go on the screen* 

dc 

h»0D* 

; A carriage return (basic = auto If) 

dc 

o 

o 


errstring 

anop 


dc 

c'This string 

should go on the paper* 

dc 

h'OD* 

; A carriage return (basic = auto If) 

dc 

o 

o 


msb 

off 


anop 



dc 

h'22* 

/ Character count 

dc 

c*A tool call 

returned with error = * 

end 
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Using the Text Tool Set 

This section discusses how the Text Tool Set routines fit into the general flow of an 
application and gives you an idea of which routines youll need to use under normal 
circumstances. Each routine is described in detail later in this chapter. 

The Text Tool Set depends on the presence of the tool sets shown in Table 23-3 and 
requires that at least the indicated version of the tool set be present. 

Table 23-3 

Text Tool Set—other tool sets required 


Tool set Tool set Minimum version 

number name needed 


$01 #01 Tool Locator 1.0 

$02 #02 Memory Manager 1.0 

Your application should make a TextStartUp call before making any other Text Tool 
Set calls. 

❖ Note: At the time of publication, the TextStartUp call was not an absolute 
requirement because the Tool Locator was automatically starting up the Text Tool 
Set at boot time. However, you should make the call anyway to guarantee that 
your application remains compatible with all future versions of the system. 

Your application should also make the TextShutDown call when the application 
quits. 

The Text Tool Set has global routines that are used to set or read the current global 
parameters used by RAM and the Pascal and BASIC text tools. The tool set also has 
I/O directing routines that direct I/O from the tool set to a specific type of character 
device driver or get information about directing a specific I/O driver. Finally, the 
tool set has text routines that interface with any BASIC, Pascal 1.1, or RAM-based 
character device driver. 
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$01 oc 


TextBootInit 

Initiali 2 e': the Text Tool Set; called only by the Tool Locator. 


Parameters 

Errors 

C 


Warning 

An application must never make this call, 

TextBootInit sets up the default device parameters as follows: 

■ Input device type is BASIC. 

■ Output device type is BASIC. 

■ Error output device type is BASIC. 

■ Input device resides in slot #3. 

■ Output device resides in slot #3. 

■ Error output device resides in slot #3. 

■ Global input AND mask is set to $FF. 

■ Global input OR mask is set to $80. 

■ Global output AND mask is set to $FF. 

■ Global output OR mask is set to $80. 

■ Global error output AND mask is set to $FF. 

■ Global error output OR mask is set to $80. 

The stack is not affected by this call. There are no input or output parameters. 
None 

Call must not be made by an application. 
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$0200 

TextStartUp 

Starts up the Text Tool Set for use by an application. Your application should make a 
TextStartUp call before making any other Text Tool Set calls. 

❖ Note: At the time of publication, the TextStartUp call was not an absolute 
requirement because the Tool Locator was automatically starting up the Text Tool 
Set at boot time. However, you should make the call anyway to guarantee that your 
application remains compatible with all future versions of the system. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void TextStartUp() 


$030C 

TextShutDown 

Shuts down the Text Tool Set when an application quits. 

Important 

If your application has started up the Text Tool Set, the application must make 
this call before It quits. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void TextShutDown() 
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$040C TextVersion 

Returns the version number of the Text Tool Set. 

Parameters 


Stack before call 


previous contents 

wordspace 

Word—Space for result 
<— SP 


Stack after call 


previous contents 
versioninfo 

Word—^Version number of Text Tool Set 

SP 

Errors None 



C extern pascal Word TextVersion() 
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$050C 


Parameters 

Errors 

C 


Text Reset 

Resets the Text Tool Set; called only when the system is reset. 


Warning 

An application must never make this call. 

Resets the device parameters to the default values as follows: 

■ Input device type is BASIC. 

■ Output device type is BASIC. 

■ Error output device type is BASIC. 

■ Input device resides in slot #3. 

■ Output device resides in slot #3. 

■ Error output device resides in slot #3. 

■ Global input AND mask is set to $FF. 

■ Global input OR mask is set to $80. 

■ Global output AND mask is set to $FF. 

■ Global output OR mask is set to $80. 

■ Global error output AND mask is set to $FF. 

■ Global error output OR mask is set to $80. 

The stack is not affected by this call. There are no input or output parameters. 
None 

Call must not be made by an application. 
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$060C TextStatus 

Indicates whether the Text Tool Set is active. 

Parameters 

Stack before call 

previous contents 
wordspace 


Word—Space for result 
<— SP 


Stack after call 
previous contents 

activeFlag Word— ^BOOLEAN; TRUE if Text Tool Set active, FALSE if inactive 

<—SP 

Errors None 

C extern pascal Boolean TextStatus{) 
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■A lisA^I':^'- 



$160C CtITextDev 

Passes a control code to a specified text device. The control codes passed depend on 
the device used and are outside the scope of this manual. 

For Pascal device drivers, this is an optional entry point that may not be supported by 
a particular Pascal device. Because BASIC devices do not support this routine, an 
error occurs if this call is made to a BASIC device. 

Parameters 


Stack before call 


previous contents 
deviceNum 
controlCode 


Word—^Device to control (0 = input, 1 = output, 2 = error outpuO 
Word—Control code (in low-order byte) to pass to device 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors $0C01 badDevType Illegal device type 

❖ Note: The remaining errors should occur only for Pascal devices. 


$0C02 

badDevNum 

Illegal device number 

$0C03 

badMode 

Illegal operation 

$0C04 

unDefHW 

Undefined hardware error 

$0C05 

lostDev 

Lost device: device no longer on-line 

$0C06 

lostFile 

File no longer in diskette directory 

$0C07 

badTitle 

Illegal filename 

$0C08 

noRoom 

Insufficient space on specified diskette 

$0C09 

noDevice 

Specified volume not on-line 

$0C0A 

noFile 

Specified file not in direaory of specified volume 

$0C0B 

dupFile 

Duplicate file: attempt to rewrite a file when a file of 
that name already exists 

$0C0C 

notClosed 

Attempt to open file that is already open 
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$0C0D 

notOpen 

Attempt to access a closed file 

$0C0E 

badFormat 

Error in reading real or integer number 

$0C0F 

ringBuffOFlo 

Ring buffer overflow: characters arriving faster than 
the input buffer can accept them 

$0C10 

writeProtected 

Specified diskette is write protected 

$0C40 

devErr 

Device error: device failed to complete a read or 
write correctly 


C extern pascal void CtlTextDev(deviceNum,controlCode) 

Word deviceNum; 

Word controlCode; 
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$1F0C ErrWriteBlock 

Combines a specified character string with the output global masks and then writes the 
string to the error output text device. The string is specified by the parameters 
textPtr+ offset, with die length specified by the cown/parameter. 


Parameters 


Stack before call 



Long—POINTER to start of ASCII text 

Word—Offset within ASCII text 
Word—String length 
<—SP 


Stack after call 


previous contents 


<r- SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal void ErrWriteBlock(textPtr,offset,count) 

Pointer textPtr; 

Word offset; 

Word count; 
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$190C ErrWriteChar 

Combines a specified character with the output global AND mask and OR mask and 
writes the character to the error output text device. 

Parameters 

Stack before call 
previous contents 

theChar Word—Character to write (in low-order byte) 

<—SP 


Stack after call 


previous contents 


SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 


C 


extern pascal void ErrWriteChar(theChar) 
Word theChar; 
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$2 IOC ErrWriteCStrfng 

Combines a pointed-to C-type string (string terminates with $00) with the output 
global masks and then writes the string to the error output text device. 

Parameters 

Stack before call 

previous contents 

cStrPtr — Long—POINTER to C-type string to be written 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal void ErrWriteCString(cStrPtr) 

Pointer cStrPtr; 
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$1B0C ErrWriteLine 

Combines a pointed-to Pascal-type string (first byte of string specifies length) with the 
output global masks and then writes the string to the error output text device. For 
BASIC and RAM-based drivers, the routine concatenates a carriage return to the 
string. For Pascal drivers, the routine concatenates a carriage return and a line feed 
to the string. 

Parameters 

Stack before call 

previous contents 

strPtr — Long—POINTER to Pascal-type string 

<—SP 


Stack after call 

previous contents I 

|<— SP 

Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal void ErrWriteLine(strPtr) 

Pointer strPtr; 
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$1D0C ErrWriteString 

Combines a pointed-to Pascal-type string (first byte of string specifies length) with the 
output global masks and then writes the string to the error output text device. 

Parameters 

Stack before call 

previous contents 

strPtr — Long—POINTER to Pascal-type string to be written 

<—SP 


Stack after caU 


previous contents 


<—SP 


Errors Pascal device errors 


Any of the errors $0C02-$0C40 as listed in the 
section “Text Tool Set Summary” at the end of this 
chapter 


C 


extern pascal void ErrWriteString(strPtr) 
Pointer strPtr; 
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$OEOC GetErrGlobals 

Returns the current values for the error output device global parameters. 

Parameters 


Stack before call 


previous contents 
wordspace 
wordspace 


Word—^Space for result 
Word—Space for result 


<— SP 


Stack after call 

Word—Global AND mask for error output device Oow-order byte only) 
Word—Global OR mask for error output device Oow-order byte only) 
<— SP 

Errors None 


previous contents 
andMask 
orMask 


C 


extern pascal TxtMaskRec GetErrGlobals() 
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$1400 GetErrorDevice 

Returns the type of driver installed as the error output device. For BASIC or Pascal 
device drivers, also returns the slot number; for RAM-based drivers, returns a pointer 
to the jump table. 

Parameters 

Stack before call 

previous contents 
wordspace 

longspace 


Word—Space for result 
Long—Space for result 
<r- SP 


Stack after call 


previous contents 
deviceType 


Word—^Error output device type (0 = BASIC, 1 = Pascal, 2 = RAM-based) 


ptrOrSlot 


Long—Slot number for BASIC or Pascal driver, or 

POINTER to jump table for RAM-based driver 

<— SP 


Errors 

C 


None 

extern pascal DeviceRec GetErrorDevice() 
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$OCOC Getineiobals 

Returns the current values for the input device global parameters. 

Parameters 

Stack before call 

previous contents 
wordspace 
wordspace 


Word—Space for result 
Word—Space for result 
SP 


Stack after call 


previous contents 
andMask 
orMask 


Word—Global AND mask for input device Oow-order byte only) 
Word—Global OR mask for input device Oow-order byte only) 
SP 


Errors None 

C extern pascal TxtMaskRec GetInGlobals() 
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$1200 GetinputDevice 

Returns the type of driver installed as the input device. For BASIC or Pascal device 
drivers, also returns the slot number; for RAM-based drivers, returns a pointer to the 
jump table. 

Parameters 

Stack before call 

previous contents 
wordspace 

longspace 


Word—Space for result 
Long—Space for result 
<—SP 


Stack after call 
previous contents 


deviceType 


ptrOrSlot 


Errors 

C 


Word—Input device type (0 = BASIC, 1 = Pascal, 2 = RAM-based) 

Long—Slot number for BASIC or Pascal driver, or POINTER to jump 
table for RAM-based driver 

<—SP 


None 

extern pascal DeviceRec GetinputDevice() 
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$ODOC GetOutGlobals 

Returns the current values for the output device global parameters. 

Parameters 

Stack before call 

previous contents 
wordspace 
wordspace 


Word—Space for result 
Word—^Space for result 
SP 


Stack after call 


previous contents 
andMask 
orMask 


Word—Global AND mask for output device Oow-order byte only) 
Word—Global OR mask for output device Oow-order byte only) 
SP 


Errors None 

C extern pascal TxtMaskRec GetOutGlobals() 
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$1300 GetOutputDevice 

Returns the type of driver installed as the output device. For BASIC or Pascal device 
drivers, also returns the slot number; for RAM-based drivers, returns a pointer to the 
jump table. 

Parameters 

Stack before call 

previous contents 
wordspace 

longspace 


Word—Space for result 
Long—Space for result 
<—SP 


Stack after call 


previous contents 
deviceType 

ptrOrSlot 


Word—Output device type (0 = BASIC, 1 = Pascal, 2 = RAM-based) 

Long—Slot number for BASIC or Pascal driver, or POINTER to jump 
table for RAM-based driver 

<— SP 


Errors None 


C 


extern pascal DeviceRec GetOutputDevice() 
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$1500 InitTextDev 

Initializes a spedned text device. 

Parameters 

Stack before call 
previous contents 

deviceNum Word—^Device to initialize (0 = input, 1 = output, 2 = error outpuO 

SP 

Stack after call 

previous contents I 

j<—SP 

Errors $0C01 badDevType Illegal device type 

C extern pascal void InitTextDev(deviceNum) 

Word deviceNum; 
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$2200 ReadChar 

Reads a charaaer obtained from the input text device, combines it with the input 
global masks, and returns the character on the stack. If echoFlag is set to a value of 
$0001, the character is also written to the output device. 

Parameters 

Stack before call 

previous contents 
wordspace 
echoFlag 


Word—Space for result 

Word—Echo or don’t echo character to output device (see Figure 23-1) 
<— SP 


Stack after call 


Word—Character (in low-order byte) 

<— SP 

Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal Word ReadChar(echoFlag) 

Word echoFlag; 


previous contents 
char 


The echo-flag word 

The values for echoFlag are illustrated in Figure 23-1. 


16 

14 13 

12 

11 

10 

9 8 7 6 5 

4 3 2 10 

1 . J 



3 


Reserved; set to 0 


echo 

Echo characters to output device = 1 
Don't echo characters = 0 


Figure 23-1 

Character echo-flag word 
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$240C ReadLine 

Reads a character string from the input text device, combines it with the input global 
masks, and writes the string to the memory location starting at bufferPtr. The 
character string is terminated when one of the following conditions is met: 

□ An End-of-line (EOL) character is received. 

□ The count of characters received is equal to the maximum line length specified by 
maxCount. 

If echoFlag is set to a value of $0001, the characters are also written to the output 
device. The echoFlag is illustrated in Figure 23-1 in the section “ReadChar” in this 
chapter. 

The count of characters received is returned on the stack. 

Parameters 

Stack before call 

previous contents 
wordspace 

bufferPtr 

maxCount 
eolChar 
echoFlag 


Word—Space for result 

Long—POINTER to start of buffer, where characters will be written 

Word—Maximum line length 

Word—End-of-line character in low byte 

Word—Echo or don’t echo characters to output device (see Figure 23-1) 
SP 


Stack after call 
previous contents 

charCount Word—Count of characters received 

<—SP 

Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 
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c 


extern pascal Word ReadLine(bufferPtr,maxCount,eolChar,echoFlag) 


Pointer 

Word 

Word 

Word 


bufferPtr; 

maxCount; 

eolChar; 

echoFlag; 
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$OBOC SetErrGlobals 

Sets the global parameters for the error output device. 

Parameters 

Stack before call 

previous contents 
andMask 
orMask 


Word—Global AND mask for error output device Oow-order byte only) 
Word—Global OR mask for error output device Oow-order byte only) 
«-SP 


Stack after call 
previous contents 




<r-SV 

Errors 

None 


C 

extern 

pascal void SetErrGlobals(andMask,orMask) 


Word 

andMask; 


Word 

orMask; 


You can also use the following alternate form of the call: 

extern pascal void SetErrGlobals(mask) 

TxtMaskRec mask; 
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$110C SetErrorDevice 

Sets the error output device to a specified type and location. The routine returns an 
error if the device'I)/pe specified is greater than 2. 


Parameters 


Stack before call 
previous contents 


deviceiype 


ptrOrSlot 


Word—Error output device (0 = BASIC, 1 = Pascal, 2 = RAM based) 

Long —Slot number for BASIC or Pascal driver, or POINTER to jump 
table for RAM-based driver 

<—SP 


Stack after call 

previous contents I 

j<—SP 

Errors $0C01 badDevType Illegal device type 

C extern pascal void SetErrorDevice(deviceType,ptrOrSlot) 

Word deviceType; 

LongWord ptrOrSlot; 

You can also use the following alternate form of the call: 
extern pascal void SetErrorDevice(deviceRec) 

DeviceRec deviceRec; 
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$090C 


SetInGlobals 

Sets the global parameters for the input device. 


Parameters 

Stack before call 


Word—Global AND mask for input device Oow-order byte only) 
Word—Global OR mask for input device Oow-order byte only) 
SP 


previous contents 
andMask 
orMask 


Stack after call 

previous contents I 

SP 

Errors None 

C extern pascal void SetInGlobals(andMask,orMask) 

Word andMask; 

Word orMask; 

You can also use the following alternate form of the call: 

extern pascal void SetInGlobals(mask) 

TxtMaskRec mask; 
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$OFOC SetinputDevice 

Sets the input device to a specified tj^se and location. The routine returns an error if 
the deviceType is greater than 2. 

Parameters 


Stack before call 

previous contents 
deviceType 

ptrOrSlot 


Word—Input device type (0 = BASIC, 1 = Pascal, 2 = RAM based) 

Long—Slot number for BASIC or Pascal driver, or POINTER to jump 
table for RAM-based driver 

4-SP 


Stack after call 


previous contents 


<— SP 


Errors $0C01 badDevType Illegal device type 

C extern pascal void SetinputDevice(deviceType,ptrOrSlot) 

Word deviceType; 

LongWord ptrOrSlot; 

You can also use the following alternate form of the call: 
extern pascal void SetinputDevice(deviceRec) 

DeviceRec deviceRec; 


(continued) 
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Assembly-language examples 


BASIC example 


PEA 0000 

; BASIC type 

PEA 000 

; in slot 3 

PEA 003 


_SetInputDevice 


RAM-based example 


PEA 002 

; RAM-based type 

PEA label/256 

; RAM driver location 

PEA label 


_SetInputDevice 
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$OAOC SetOutGlobals 

Sets the global parameters for the output device. 

Parameters 


Stack before call 


previous contents 
andMask 
or Mask 


Word—Global 
Word—Global 
<—SP 


AND mask for output device Qow-order byte only) 
OR mask for output device Qow-order byte only) 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetOutGlobals(andMask,orMask) 

Word andMask; 

Word orMask; 

You can also use the following alternate form of the call: 

extern pascal void SetOutGlobals(mask) 

TxtMaskRec mask; 
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$100C SetOutputDevice 

Sets the output device to a specified type and location. The routine returns an error if 
the cteviceT^ specified is greater than 2. 

Parameters 


Stack before call 

previous contents 
deviceType 

ptrOrSlot 


Word—Output device type (0 = BASIC, 1 = Pascal, 2 = RAM based) 

Long—Slot number for BASIC or Pascal driver, or POINTER to jump 
table for RAM-based driver 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors $0C01 badDevType Illegal device type 

C extern pascal void SetOutputDevice(deviceType,ptrOrSlot) 

Word deviceType; 

LongWord ptrOrSlot; 

You can also use the following alternate form of the call: 

extern pascal void SetOutputDevice(deviceRec) 

DeviceRec deviceRec; 
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$170C StatusTextDev 

Executes a status call to a specified text device. The routine returns an error if the 
device is not ready. 


Warning 

BASIC devices do not support this routine. 


Parameters 

Stack before call 

previous contents 
deviceNum 
requestCode 


Word—^Device for inquiry (0 = input, 1 = output, 2 = error output) 
Word—Request code (in low-order byte) to pass to deviceNum 
SP 


Stack after call 

( previous contents I 

|<—SP 

Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal void StatusTextDev(deviceNum,requestCode) 

Word deviceNum; 

Word requestCode; 
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$230C TextReadBlock 

Reads a block of characters from the input text device, combines them with the input 
global masks, and writes the block to the memory location at buJferPtr + offset. 

If echoFlagiS set to a value of $0001, the characters are also written to the output 
device. The echoFlag word is illustrated in Figure 23-1 in the section “ReadChar” in 
this chapter. 

Parameters 

Stack before call 

previous contents 
bufferPtr 

offset 
blockSize 
echoFlag 


Long—POINTER to start of block 

Word—Offset to start of block to be read 
Word—^Size of block to be read 

Word—Echo or don’t echo characters to output device (see Figure 23-1) 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary’’ at the end of this 
chapter 

C extern pascal void TextReadBlock(bufferPtr,offset,blockSize,echoFlag) 


Pointer 

bufferPtr; 

Word 

offset; 

Word 

blockSize; 

Word 

echoFlag; 
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$1E0C TextWriteBlock 

Combines a specified charaaer string with the output global masks and then writes the 
string to the output text device. The string is specified by the textPtr + offset 
parameters, with the length specified by the count parameter. 


Parameters 


Stack before call 



Long—POINTER to Start of ASCII text 

Word—Offset within ASCII text 
Word—String length 
<—SP 


Stack after call 


previous contents 


4- SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal void TextWriteBlock(textPtr,offset,count) 

Pointer textPtr; 

Word offset; 

Word count; 
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$180C WriteChar 

Combines a specified character with the output global AND mask and OR mask and 
writes the character to the output text device. 

Parameters 

Stack before call 

previous contents 

theChar Word—Character to write (in low-order byte) 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 


C 


extern pascal void WriteChar(theChar) 
Word theChar; 
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$200C WriteCString 

Combines a pointed-to C-type string (string terminates with $00) with the output 
global masks and then writes the string to the output text device. 

Parameters 

Stack before call 
previous contents 

cStrPtr — Long— POINTER to C-type string to be written 

<—SP 


Stack after call 
I previous contents 


<— SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal void WriteCString(cStrPtr) 

Pointer cStrPtr; 
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$1A0C WriteLine 

Combines a pointed-to Pascal-type string (first byte of string specifies length) with the 
output global masks and then writes the string to the output text device. For BASIC 
and RAM-based drivers, the routine concatenates a carriage return to the string. For 
Pascal drivers, the routine concatenates a carriage return and a line feed to the string. 

Parameters 

Stack before call 

previous contents 

strPtr — Long—POINTER to Pascal-type string to be written 

SP 


Stack after call 


previous contents 


SP 


Errors Pascal device errors 


Any of the errors $0C02-$0C40 as listed in the 
section “Text Tool Set Summary” at the end of this 
chapter 


C 


extern pascal void WriteLine(strPtr) 
Pointer strPtr; 
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$1C0C Writestring 

Combines a pointed-to Pascal-type string (first byte of string specifies length) with the 
output global masks and then writes the string to the output text device. 

Parameters 

Stack before call 

previous contents 

strPtr — Long—POINTER to Pascal-type string to be written 

<— SP 


Stack after call 


previous contents 


<—SP 


Errors Pascal device errors Any of the errors $0C02-$0C40 as listed in the 

section “Text Tool Set Summary” at the end of this 
chapter 

C extern pascal void WriteStrlng(strPtr) 

Pointer strPtr; 
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Text Tool Set summary 

This section briefly summarizes the constants and tool set errors contained in the 
Text Tool Set. There are no predefined data stmctures for the Text Tool Set. 


Important 

These definitions are provided in the appropriate Interface file. 


Table 23-4 

Text Tool Set constants 


Name 

Value 

Description 

Echo flag values 

noEcho 

$0000 

Don’t echo characters to output device 

echo 

$0001 

Echo characters to output device 

Device numbers 

input 

$0000 

Input device 

output 

$0001 

Output device 

errorOutput 

$0002 

Error output device 

Device types 

basicType 

$0000 

Basic device type 

pascalType 

$0001 

Pascal device type 

ramBased 

$0002 

RAM-based device type 
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Table 23-5 

Text Tool Set error codes 


Code 

Name 

Description 

$0C01 

badDevType 

Illegal device type 

$0C02 

badDevNum 

Illegal device number 

$0C03 

badMode 

Illegal operation 

$0C04 

unDefHW 

Undefined hardware error 

$0C05 

lostDev 

Lost device: device no longer on-line 

$0C06 

lostFile 

File no longer in diskette directory 

$0C07 

badTitle 

Illegal filename 

$0C08 

noRoom 

Insufficient space on specified diskette 

$0C09 

noDevice 

Specified volume not on-line 

$0C0A 

noFile 

Specified file not in directory of specified volume 

$0C0B 

dupFile 

Duplicate file: attempt to rewrite a file when a file 
of that name already exists 

$0C0C 

notClosed 

Attempt to open file that is already open 

$0C0D 

notOpen 

Attempt to access a closed file 

$0C0E 

badFormat 

Error in reading real or integer number 

$0C0F 

ringBuffOFlo 

Ring buffer overflow: characters arriving faster 
than the input buffer can accept them 

$0C10 

write?rotected 

Specified diskette is write-protected 

$OC40 

devErr 

Device error: device failed to complete a read or 
write correctly 


Note: With the exception of badOevType, the errors should occur only for Pascal devices. 
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Tool Locator 


The Tool Locator is the tool set that allows your application to use tool sets without 
knowing whether the tool sets are in RAM or ROM. 

In this chapter, we provide the information you need to use the existing tool sets. If 
you are writing your own tool set, however, you'll need to understand more about 
how the Tool Locator works. We have provided most of that information in 
Appendix A, “Writing Your Own Tool Set,” as a special subject; please refer to that 
appendix for more information. 


A preview of the Tool Locator routines 

To introduce you to the capabilities of the Tool Locator, all Tool Locator routines are 
grouped by function and briefly described in Table 24-1. These routines are 
described in detail later in this chapter, where they are separated into housekeeping 
routines (discussed in routine number order) and the rest of the Tool Locator 
routines (discussed in alphabetical order). 









Table 24-1 

Tool Locator routines and their functions 


Routine 


Housekeeping routines 

TLBootInit 

TLStartUp 

TLShutDown 

TLVersion 

TLReset 

TLStatus 

Tool locating routines 
LoadTools 

LoadOneTool 

UnloadOneTool 

GetFuncPtr 

GetTSPtr 

SetTSPtr 

GetWAP 

SetWAP 

TLMountVolume 

TLTextMountVolume 

SaveTextState 

RestoreTextState 

MessageCenter 


Description 


Initializes the Tool Locator and all other ROM-based tool sets—must not be 
called by an application 

Starts up the Tool Locator for use by an application 
Shuts down the Tool Locator when an application quits 
Returns the version number of the Tool Locator 

Resets the Tool Locator and all other ROM-based tool sets when the system is 
reset—^must not be called by an application 
Indicates whether the Tool Locator is active 


Ensures that specified system tool sets are available and have specified 
minimum version numbers 

Ensures that a specified system tool set is available and has a specified 

minimum version number 

Unloads a specified tool set from memory 

Returns an entry in the function pointer table for a specified function in a 
specified tool set 

Returns the pointer to the function pointer table of a specified tool set 
Installs the pointer to a function pointer table in the appropriate tool pointer 
table 

Gets the pointer to the work area for a spedfied tool set 

Sets the pointer to the work area for a spedfied tool set 

Displays on the Super Hi-Res display a simulated dialog box that your 

application can use to ask the user to mount a volume 

Displays on the 40-column text screen a simulated dialog box that your 

application can use to ask the user to mount a volume 

Saves the state of the text screen and forces the hardware to display the text 

screen regardless of the display mode in use 

Restores the state of the text screen from a spedfied handle and disposes of 
the handle 

Allows applications to communicate with each other 
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Using the Tool Locator 

This section discusses how some of the Tool Locator routines fit into the general flow 
of an application and gives you an idea of which routines youll need to use under 
normal circumstances. Each routine is described in detail later in this chapter. 

The Tool Locator does not depend on the presence of any of the other tool sets; 
rather, all other tool sets depend on the Tool Locator, 

The first Tool Locator call your application must make is TLStartUp. TLStartUp starts 
the Tool Locator mechanism that allows the other tool sets to be found. Conversely, 
when you quit your application, you must make the TLShutDown call just before the 
application quits. 

Your application ensures that the tool sets it needs are available—^and that they meet 
specified minimum version requirements—^by making a LoadTools call. If, for 
example, you wanted to use the LineEdit Tool Set routine LETextBox2, which is 
available only in versions 2.0 and later of the tool set, you would specify 2.0 as the 
minimum version for the LineEdit Tool Set in the LoadTools call. The LoadTools 
routine loads all the tool sets that meet the minimum version requirements of those 
specified in the routine, thus making them available for the life of the application. 

RAM-based tool sets are loaded only when the application requests they be loaded. 
Thus, if you want to load a tool set just before your application uses it, you can use the 
LoadOneTool routine (this routine also checks for the minimum tool set version). 
When you are finished with the tool set, you can unload it by using the 
UnloadOneTool routine. 

The routines TLMountVolume and TLTextMountVolume can help if the boot disk 
containing the specified tool set (in the TOOLS subdirectory of the SYSTEM 
directory) is not available when the tool set is requested. TLMountVolume provides 
a mechanism your application can use to display a prompting message and OK and 
Cancel buttons on the Super Hi-Res display. TLTextMountVolume performs the 
same function (with a message only, no buttons) for the 40-column text display. 

You can use the SaveTextState and RestoreTextState routines to save and restore the 
state of the text screen. You can use the MessageCenter call to communicate with 
other applications. 

Normally, your application won't need to use the GetWap, SetWap, GetTSPtr, 
SetTSPtr, and GetFuncPtr calls; those calls are used only when you are writing your 
own tool set (see Appendix A, “Writing Your Own Tool Set," for more details). 
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$0101 

TLBootInit 

Initializes the Tool Locator and all other ROM-based tool sets; called only by the 
system startup firmware. 

Warning 

An application must never make this call. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

Call must not be made by an application. 


$0201 

TLStartUp 

Starts up the Tool Locator for use by an application. 

Important 

Your application must make this call before it makes any other tool calls. 

Parameters 

The stack is not affected by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void TLStartUp() 
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$0301 TLShutDown 

Shuts down the Tool Locator when an application quits. 

Important 

Your application must make this call Just before it quits. 

Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C extern pascal void TLShutDown() 


$0401 TLVersion 

Returns the version number of the Tool Locator. 

Parameters 

Stack before call 

previous contents 
wordspace 

Stack after call 

previous contents 

versioninfo Word —Version number of Tool Locator 

SP 

Errors None 

C extern pascal Word TLVersion() 


Word —Space for result 
4-SP 
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$0501 TLReset 

Resets the Tool Locator and all other ROM-based tool sets when the system is reset; 
called only by the system firmware. 


Warning 

An application must never make this call. 

Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C Call must not be made by an application. 


$0601 TLStatus 

Indicates whether the Tool Locator is active. 

Parameters 

Stack before call 
previous contents 

wordspace Word—Space for result 

<— SP 


Stack after call 


previous contents 
activeFlag 


Word—BOOLEAN; TRUE CTool Locator is always active) 

<—SP 


Errors None 

C extern pascal Boolean TLStatus() 
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$0B01 GetFuncPtr 

Returns an entry in the function pointer table for a specified function in a specified 
tool set. 

❖ Note: The word containing funcNum and tsNum is the same as the number the 
Tool Locator normally uses to locate the routine. For example, the appropriate 
number for GetFuncPtr is $0B01. 


Parameters 


Stack before call 
previous contents 


longspace 


Long—Space for result 


userOrSystem 
funcNum I tsNum 


Word—^$0000 = system tool set; $8000 = user tool set 
Byte—Function number I Byte—^Tool set number 

<—SP 


Stack after call 


previous contents 
fptEntry 


Long—Entry in function pointer table 


<— SP 


Errors 


C 


$0001 toolNotFoundErr Specified tool set not found 
$0002 funcNotFoundErr Specified routine not found 

extern pascal Pointer GetFuncPtr(userOrSystem,funcTSNum) 
Word userOrSystem; 

Word funcTSNum; 
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$0901 GetTSPtr 

Returns the pointer to the function pointer table of a specified tool set. 

❖ Note: This call is normally used only if you are writing your own tool set. See 
Appendix A, “Writing Your Own Tool Set,” for more information. 


Parameters 


Stack before call 


previous contents 


longspace 


Long—Space for result 


userOrSystem 

tsNum 


Word—^$0000 = system tool set; $8000 = user tool set 
Word—^Tool set number of tool set whose pointer is to be returned 
SP 


Stack after call 


previous contents 
JptPtr 


Long—POINTER to function pointer table of tool set 
<— SP 


Errors 

$0001 

toolNotFoundErr Specified tool set not found 

C 

extern 

pascal Pointer GetTSPtr(userOrSystem,tsNum) 


Word 

userOrSystem; 


Word 

tsNum; 


24-8 


Tool Locator routines 














$0C01 Get WAP 

Gets the pointer to the work area for a specified tool set. 

❖ Note. This call is normally used only if you are writing your own tool set. See 
Appendix A, “Writing Your Own Tool Set,” for more information. 


Parameters 

Stack before call 

Long—Space for result 

Word—^$0000 = system tool set; $8000 = user tool set 
Word—Number of tool set 
<—SP 


previous contents 

longspace 

userOrSystem 

tsNum 


Stack after call 
previous contents 
waptPtr 


Long—POINTER to work area of tool set 


^SP 


Errors 


$0001 toolNotFoundErr Specified tool set not found 


C 


extern pascal Pointer GetWAP(userOrSystem,tsNum) 
Word userOrSystem; 

Word tsNum; 


Tool Locator routines 


24-9 















$0F01 LoadOneTool 

Ensures that a specified system tool set is available Goading it from disk if necessary) 
and has at least a specified minimum version number. If the minimum version of the 
tool is not available in the TOOLS subdirectory of the SYSTEM directory in the boot 
volume, an error occurs. 

❖ Note: See the section “LoadTools” in this chapter for a list of tool set numbers. 


Parameters 


Stack before call 


previous contents 
toolNumber 
minVersion 


Word—INTEGER; tool set number of tool set to load 
Word—Minimum version number of tool set needed 

SP 


Stack after call 


previous contents 


<—SP 


Errors 


C 


$0001 toolNotFoundErr 
$0010 toolVersionErr 
System Loader errors 
ProDOS errors 


Specified tool set not found 
Specified minimum version not found 
Returned unchanged 
Returned unchanged 


extern pascal void LoadOneTool(toolNumber,minVersion) 
Word toolNumber; 

Word minVersion; 
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$0E01 LoadTools 

Ensures that specified system tool sets are available and checks that the tool sets have 
at least a specified minimum version number. The call needs, as input, a pointer 
to a tool table. The tool table lists the total number of tool sets, the number of each 
tool set needed, and the minimum acceptable version number of each tool set. 

The stmcture of the tool table is illustrated in Figure 24-1. The numbers of the tool sets 
are given in Table 24-2. 


Important 

RAM-based tools are loaded from the TOOLS subdirectory of the SYSTEM 
directory. Each tool set is a load file of type $BA and Is named after Its decimal 
tool set number (Tool 23 is in a file named TOOL023, and so on). 


Parameters 

Stack before call 
previous contents 

toolTablePtr — Long—POINTER to table of tool set numbers 

<— SP 


Stack after call 


previous contents 




<— SP 


Errors $0001 

toolNotFoundErr 

Specified tool set not found 

$0010 

toolVersionErr 

Specified minimum version not found 

System Loader errors 

Returned unchanged 

ProDOS 

errors 

Returned unchanged 


C 


extern pascal void LoadTools(toolTablePtr) 
Pointer toolTablePtr; 


(continued) 
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Tool table 

The form the tool table must take is shown in Figure 24-1. 


Tool 

set 

number 


Count 



Minimum 
version 
of tool set 


Figure 24-1 

Tool table 

Thus, in assembly language the table looks like this: 

dc i'NumToolsRequired* 
dc i*ToolNuml,MinVersion* 
dc i*ToolNum2,MinVersion» 


dc i'ToolNumN,MinVersion* 

The format of the tninVersion word is as follows: 

High-order byte = Major version 
Low-order byte = Minor version 

Thus, a value of $0201 means a major version of 2 and a minor version of 1, and is 
commonly referred to as “Version 2.1.” 
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Tool set numbers 

The tool set numbers of all of the tool sets are listed in Table 24-2. 

Table 24-2 
Tool set numbers 

Tool set Tool set 

number name 


$01 

#01 

Tool Locator 

$02 

#02 

Memory Manager 

$03 

#03 

Miscellaneous Tool Set 

$04 

#04 

QuickDraw n 

$05 

#05 

Desk Manager 

$06 

#06 

Event Manager 

$07 

#07 

Scheduler 

$08 

#08 

Sound Tool Set 

$09 

#09 

Apple Desktop Bus Tool Set 

$0A 

#10 

SANE Tool Set 

$0B 

#11 

Integer Math Tool Set 

$0C 

#12 

Text Tool Set 

$0D 

#13 

Reserved for internal use 

$0E 

#14 

Window Manager 

$0F 

#15 

Menu Manager 

$10 

#i6 

Control Manager 

$11 

#17 

System Loader 

$12 

#18 

QuickDraw II Auxiliary 

$13 

#19 

Print Manager 

$14 

#20 

LineEdit Tool Set 

$15 

#21 

Dialog Manager 

$16 

#22 

Scrap Manager 

$17 

#23 

Standard File Operations Tool Set 

$18 

#24 

Not available 

$19 

#25 

Note Synthesizer 

$1A 

#26 

Note Sequencer 

$1B 

#27 

Font Manager 

$1C 

#28 

List Manager 
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$1501 


MessageCenter 

Allows applications to communicate with each other. 


Important 

This routine is avaiiabie only in Version 2.1 or iater of the Tool Locator. 


The message types are administered by Developer Technical Support at Apple 
Computer. 


Parameters 
Stack before call 

Word—1 = add, 2 = get, 3 = delete (see Table 24-3) 
Word—^Message ID number 

Long—HANDLE to message 
<— SP 


previous contents 
action 
type 


— messageHandle — 


Stack after call 
previous contents 


<— SP 


Errors 


$0111 messNotFoundErr Specified message not found 


C 


extern pascal void MessageCenter(action,type,messageHandle) 
Word action; 

Word type; 

Handle messageHandle; 
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More about messages 

The action codes the routine will recognize are shown in Table 24-3. 

Table 24-3 

MessageCenter action codes 

Type Name Description 


1 addMessage Adds the specified message to the message center data. 

The type is the ID of the message being added; any 
message already in the message center with this type is 
deleted. This message does not alter the 
messageHandle. 

2 getMessage Returns the specified message from the message center. 

If there is no message with the specified ID, an error 
occurs and the messageHandle is not altered. The 
messageHandle block can be of any size; the routine will 
resize the block to fit the data being returned. 

3 deleteMessage Deletes a specified message from the message center. If 

the message does not appear in the message center, an 
error occurs. The messageHandle is not used for this 
call, and any value may be passed. 


The actual data in the message must begin with six bytes of reserved space, as follows: 

MessNext LONG Handle of next message 

MessType WORD Type of this message 

MessData block Message-specific data 

The only message defined at the time of publication is type 1. That message type is 
used to pass file information from one application to another. For example, a 
Finder-type application needs to tell other applications what documents it should 
open or print. In this case, the message data is set up as follows: 

MessNext LONG 

MessType WORD 1; file info type 

MessData block 0 = open the following files 

1 = print the following files 

str ’nameT 

str ’full pathname 2' 

BYTE 0 
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$1401 RestoreTextState 

Restores the state of the text screen from a specified handle and disposes of the 
handle. The state of the text screen can be saved with a SaveTextState call; see the 
section “SaveTextState” in this chapter. 


Parameters 

Stack before call 
previous contents 

stateHandle — Long —handle to state record to restore 

^SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void RestoreTextState(stateHandle) 

Handle stateHandle; 
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$1301 SaveTextState 

Saves the state of the text screen and forces the hardware to display the text screen 
regardless of the display mode in use. The routine does not initiali 2 e the Text Tool 
Set. 


Important 

This routine Is available only in Version 2.1 or later of the Tool Locator. 


Parameters 


Stack before call 
previous contents 


longspace 


Long—Space for result 
<—SP 


Stack after call 
previous contents 


stateHandle 


Errors 

C 


Long—HANDLE to State record (see Table 24-4) 

-SP 

None 

extern pascal Handle SaveTextState() 


(continued) 
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The SaveTextState record 


The structure of the record in which the SaveTextState information is saved is private. 
At the time of publication, the various entities saved included those shown in 
Table 24-4. 


Table 24-4 

State record 


Entity 

Description 

StateReg 

Language card information 

80Col 

40 or 80 columns 

NewVideo 

New video register 

Text 

Text state soft switch 

Mix 

Split mode soft switch 

Page2 

Page 1 or page 2 

HiRes 

HiRes or LoRes 

AltCharSet 

Character set 

SOVid 

State of 80 store 

Cursor 

Internal cursor variable 

c3ROM 

State of the slot 3 firmware 

OutputDevice 

Text tools output device 

OutGlobals 

Text tools output globals 

InputDevice 

Text tools input device 

InGlobals 

Screen Memory 
in bank $0 

Screen Memory 
in bank $1 

Screen Memory 
in bank $E0 
Screen Memory 
in bank $E1 
Screen holes for 
Slots 

Text tools input globals 
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$0A01 SetTSPtr 

Installs the pointer to a function pointer table in the appropriate tool pointer table 
(TPT). 

❖ Note: This call is normally used only if you are writing your own tool set. See 
Appendix A, “Writing Your Own Tool Set,” for more information. 

If the TPT is not yet in RAM, the routine copies it to RAM. (Memory for the TPT is 
obtained from the Memory Manager.) If there is not enough room in the TPT for the 
new entry, the TIT is moved to a bigger chunk of memory. Likewise, the Work Area 
Pointer Table (WAPT) is expanded, if necessary (memory for the expansions is 
obtained from the Memory Manager). 

If the new pointer table has any 0 entries, old entries are moved from the old pointer 
table to the new pointer table. This feature makes it possible, for example, to patch 
just a portion of a tool set rather than replacing the tool set entirely. 


Parameters 

Stack before call 

Word—$0000 = system tool set, $8000 = user tool set 
Word—^Tool set number of tool set 

Long—POINTER to function pointer table for tool set 
<— SP 


previous contents 
userOrSystem 
tsNum 


JptPtr 


Stack after call 


previous contents 


<— SP 


Errors $0001 toolNotFoundErr Specified tool set not found 

C extern pascal void SetTSPtr(userOrSystem,tsNum,fptPtr) 

Word userOrSystem; 

Word tsNum; 

Pointer fptPtr; 
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$0D01 SetWAP 

Sets the pointer to the work area for a specified tool set. 

❖ Note: This call is normally used only if you are writing your own tool set. See 
Appendix A, “Writing Your Own Tool Set," for more information. 

Parameters 

Stack before call 

previous contents 
userOrSystem 
tsNum 

waptPtr 


Word—$0000 = system tool set; $8000 = user tool set 
Word—^Tool set number of tool set 

Long—POINTER to work area of tool set 

SP 


Stack after call 
previous contents 


Errors 

C 


<— SP 

$0001 toolNotFoundErr Specified tool set not found 

extern pascal void SetWAP(userOrSystem,tsNum,waptPtr) 
Word userOrSystem; 

Word tsNum; 

Pointer waptPtr; 
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$1101 TLMountVolume 

Displays on the Super Hi-Res display a simulated dialog box that your application can 
use to ask the user to mount a volume. The routine also displays two buttons. 

❖ Note: The box is not really a dialog box because it is not under the control of the 
Dialog Manager (a RAM-based tool set that might not be active). 

The text displayed must be supplied by the application (and can therefore be easily 
translated into other languages). The contents of the screen under the box are saved 
before the box is drawn and are restored after the user responds. The button may be 
chosen by the user either by clicking on it with the mouse button or by pressing the 
Return key for button 1 or the Esc (escape) key for button 2. 


Important 

Your application must make sure that the text passed in the strings fits in the 
area provided. 


Parameters 


Stack before call 


previous contents 


wordspace 

whereX 

whereY 

linelPtr 

— 

Hne2Ptr 

— 

butlPtr 

— 

but2Ptr 

— 


Word—Space for result 
Word—INTEGER; upper left X 
Word—INTEGER; upper left Y 

Long—POINTER to Pascal-type 

Long—POINTER to Pascal-type 

Long—POINTER to Pascal-type 

Long—POINTER to Pascal-type 
SP 


coordinate for box 
coordinate for box 

string to appear at top of box 
string to appear just below line 2 
string to appear inside button 1 
string to appear inside button 2 
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Stack after call 


previous contents 


whichButton 


Errors 

C 


Word—Button number chosen; Return = 1, Esc = 2 
SP 


None 


extern pascal Word TLMountVolume(whereX,whereY,linelPtr,line2Ptr, 
butlPtr,but2Ptr) 

Integer whereX; 

Integer whereY; 

Pointer linelPtr; 

Pointer line2Ptr; 

Pointer butlPtr; 

Pointer but2Ptr; 

You can also use the following alternate form of the call: 

extern pascal Word TLMountVolume(where,linelPtr,line2Ptr,butlPtr,but2Ptr) 


Point 

where; 

Pointer 

linelPtr; 

Pointer 

line2Ptr; 

Pointer 

butlPtr; 

Pointer 

but2Ptr; 
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$1201 TLTextMountVolume 

Displays on the 40-column text screen a simulated dialog box that your application 
can use to ask the user to mount a volume. The routine also displays two buttons. 

❖ Note: The box is not really a dialog box because it is not under the control of the 
Dialog Manager (a RAM-based tool set that might not be active). 

The text displayed must be supplied by the application (and can therefore be easily 
translated into other languages). The contents of the screen under the box are saved 
before the box is drawn and restored after the user responds. The button is chosen by 
the user pressing the Return key for button 1 or the Esc (escape) key for button 2. 


Important 

Your application must make sure that the text passed in the strings fits in the 
area provided. 


Parameters 


Stack before call 

previous contents 


wordspace 

linelPtr 

— 

line2Ptr — 

buttonlPtr 

— 

button2Ptr 

— 


Word—Space for result 
Long—POINTER to Pascal-type 

Long—POINTER to Pascal-type 

Long—POINTER to Pascal-type 

Long—POINTER to Pascal-type 
4— SP 


string to appear at top of box 
string to appear just below line 2 
string to appear inside button 1 
string to appear inside button 2 


Stack alter call 

previous contents 
whichButton 


Word—Button number chosen; Return = 1, Esc = 2 
<— SP 
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Errors None 

C extern pascal Word TLTextMountVolume(linelPtr,line2Ptr,butlPtr,but2Ptr) 


Pointer 

linelPtr; 

Pointer 

line2Ptr; 

Pointer 

butlPtr; 


Pointer but2Ptr; 
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$1001 UnloadOneTool 

Unloads a specified tool set from memory. See Table 24-2 in the section “LoadTools” 
in this chapter for the tool set numbers. 

The tool set is left in a restartable state; that is, the purge level of all of the tool set’s 
memory blocks is set to 3 so that the tool set may be restarted quickly. See Chapter 12, 
“Memory Manager,” in Volume 1 for more information on purge levels. 


Parameters 

Stack before call 
previous contents 

toolNumber Word—^INTEGER; tool set number of tool set to unload 

<— SP 


Stack after call 


previous contents 


<—SP 


Errors 


$0001 toolNotFoundErr Specified tool set not found 


C 


extern pascal void UnloadOneTool(toolNumber) 
Word toolNumber; 
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Tool Locator summary 

This section briefly summarizes the constants and tool set error codes contained in 
the Tool Locator. There are no predefined data structures for the Tool Locator. 


Important 

These definitions are provided in the appropriate Interface file. 


Table 24-5 

Tool Locator constants 


Name 

Value 

Description 

Message center action codes 


addMessage 

$0001 

Add message 

getMessage 

$0002 

Get message 

deleteMessage 

$0003 

Delete message 

Message center type values 


fileInfoType 

$0001 


TLMountVolume button values 


mvReturn 

$0001 

Equivalent of dialog OK button 

mvEscape 

$0002 

Equivalent of dialog Cancel button 

Tool set specification 


sysTool 

$0000 

System tool set 

userTool 

$8000 

User tool set 

Table 24-6 



Tool Locator error codes 


Code Name 


Description 


$0001 

$0002 

$0110 

$0111 


toolNotFoundErr 

funcNotFoundErr 

toolVersionErr 

messNotFoundErr 


Specified tool set not found 
Specified routine not found 
Specified minimum version not found 
Specified message not found 
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Chapter 25 


Window Manager 


The Window Manager is a tool set for dealing with windows on the Apple IIGS 
screen. The saeen represents a working surface or desktop; graphic objects appear 
on the desktop and can be manipulated with a mouse. A window is an object on the 
desktop in which information, such as a document or a picture, is presented. 
Windows can be any size or shape, and there can be one or many of them, 
depending on the application. 

Windows allow the application to control more information than the screen can 
display at one time. The name window is used because the user sees through the 
window into a larger area, as illustrated in Figure 25-1. 



Figure 25-1 

Window 























A preview of the Window Manager routines 

To introduce you to the capabilities of the Window Manager, all Window Manager 
routines are grouped by function and briefly described in Table 25-1. These routines 
are described in detail later in this chapter, where they are separated into 
housekeeping routines (discussed in routine number order) and the rest of the 
Window Manager routines (discussed in alphabetical order). 

Table 25-1 

Window Manager routines and their functions 


Routine Description 


Housekeeping routines 
WindBootInit 

WindStartUp 

WindShutDown 

WindVersion 

WindReset 

WindStatus 


Initializes the Window Manager, called only by the the Tool Locator—must not 
be called by an application 

Starts up the Window Manager for use by an application 
Shuts down the Window Manager when an application quits 
Returns the version number of the Window Manager 

Resets the Window Manager; called only when the system is reset—must not be 
called by an application 

Indicates whether the Window Manager is active 


Initiaiization and termination routines 
Desktop 

NewWindow 

CloseWindow 

WindNewRes 


Window record and 
GetWMgrPort 
SetWindowIcons 
SetWRefCon 

GetWRefCon 

SetWTitle 

GetWTitle 

SetFrameColor 

GetFrameColor 

FrontWindow 


Controls the addition of regions to and subtraction of regions from the desktop 
and controls the current desktop pattern 

Creates a specified window as specified by its parameters, adds it to the window 
list, and returns a pointer to the new window's GrafPort 

Removes a specified window from the screen, disposes of all controls associated 
with that window, and deletes the window from the window list 
Closes the Window Manager's GrafPort and opens a new GrafPort in the other 
Super Hi-Res resolution 

global access routines 

Returns a pointer to the Window Manager’s port 
Sets the icon font for the Window Manager 

Sets a value that is inside a specified window record and is reserved for the 
application’s use 

Returns a value from a a specified window’s record that was passed to either 
NewWindow or SetWRefCon by the application 

Changes the title of a specified window to a specified title and redraws the window 
Returns the pointer to a specified window’s title 
Sets the color of a specified window’s frame 
Returns the color of a specified window’s frame 

Returns a pointer to the first visible window in the window list (that is, the active 
window) 
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Table 25-1 (continued) 

Window Manager routines and their functions 
Routine Description 

Window record and global access routines 

GetFirstWindow Returns a pointer to the first window in the window list (the window may not be the 
active window) 

GetNextWindow Returns a pointer to the next window in the window list after a specified window; 

returns NIL if the specified window is the last window in the window list 
GetWKind Indicates whether a specified window is a system window or an application 

window 

SetWFrame Sets the bit flag that describes a specified window’s frame type 

GetWFrame Returns the bit flag that describes a specified window’s frame type 

GetStructRgn Returns a handle to a specified window’s structure region 

GetContentRgn Returns a handle to a specified window’s content region 

GetUpdateRgn Returns a handle to a specified window’s update region 

GetDefProc Returns a pointer to the routine that is called to draw, hit test, and otherwise 

define a window’s frame and behavior 

SetDefProc Sets the pointer to the routine that is called to draw, hit test, and otherwise define 

a window’s frame and behavior 

GetWControls Returns the handle to the first control in the window’s control list 

SetZoomRect Sets the rectangle to be used as the content’s zoomed or unzoomed size for a 

specified window 

GetZoomRect Returns a pointer to the rectangle to be used as the content’s zoomed or 

unzoomed size for a specified window 

GetSysWFlag Indicates whether a specified window is a system or an application window 

SetSysWindow Marks a specified window as a system window 

GetContentOrigin Returns the values used by TaskMaster to set the origin of the window’s GrafPort 
when handling an update event 

SetContentOrigin Sets the origin of the window’s GrafPort when handling an update event 

SetContentOrigin2 Sets the origin of the window’s GrafPort when handling an update event and 

allows the application to scroll or not scroll the window’s content region 
SetOriginMask Specifies the mask used to put the horizontal origin on a grid 

StartDrawing Makes a specified window the current port and sets its origin 

GetDataSize Returns the height and width of the data area of a specified window 

SetDataSize Sets the height and width of the data area of a specifed window 

GetMaxGrow Returns the maximum values to which a specified window’s content region can 

grow 

SetMaxGrow Sets the maximum values to which a specified window’s content region can grow 

GetScroll Returns the number of pixels by which TaskMaster will scroll the content region 

when the user selects the arrows on window frame scroll bars 
SetScroll Sets the number of pixels by which TaskMaster will scroll the content region when 

the user selects the arrows on window frame scroll bars 

(continued) 
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Table 25-1 (continued) 

Window Manager routines and their functions 


Routine Description 


Window record and global access routines 

GetPage Returns the number of pixels by which TaskMaster will scroll the content region 


SetPage 

when the user selects the page regions on window frame scroll bars 

Sets the number of pixels by which TaskMaster will scroll the content region when 
the user selects the page regions on window frame scroll bars 

GetContentDraw 

Returns the pointer to the routine that draws the content region of a specified 
window 


SetContentDraw Sets the pointer to the routine to draw the content region of a specified window 
Information bar routines 

GetInfoDraw Returns the pointer to the routine that draws the information bar for a specified 


SetInfoDraw 

window 

Sets the pointer to the routine that draws the information bar for a specified 
window 

GetInfoRefCon 

Returns the value associated with the draw information bar routine for a specified 
window 

SetInfoRefCon 

Sets the value associated with the draw information bar routine for a specified 
window 

GetRectInfo 

Sets the information rectangle to the coordinates of the information bar 
rectangle 

StartInfoDrawing 

Allows an application to draw or hit test outside of its information bar definition 
procedure 

EndlnfoDrawing 

Puts the Window Manager back into a global coordinate system 


Window shuffling routines 


SelectWindow 

Hide Window 
ShowWindow 
ShowHide 
BringToFront 

Makes a specified window the active window 

Makes a specified window invisible 

Makes a specified window visible if it was invisible and then draws the window 
Shows or hides a window 

Brings a specified window to the front of all other windows and redraws the 

SendBehind 

windows as necessary but does not do any highlighting or unhighlighting 

Changes the position of a specified window, redrawing any exposed windows 


Window drawing routines 

HiliteWindow Highlights or unhighlights a specified window 

RefreshDesktop Redraws the entire desktop and all the windows 
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Table 25-1 (continued) 

Window Manager routines and their functions 


Routine Description 


User Interaction routines 

FindWindow Indicates which part of which window, if any, the cursor was in when the user pressed 


DragWindow 

the mouse button 

Pulls around a dotted outline of a specified window, following the movements of the 
mouse until the mouse button is released 

GrowWindow 

Pulls around a grow image of a specified window, following the movements of the 
mouse until the mouse button is released 

TradcGoAway 

Tracks the mouse until the mouse button is released, highlighting the go-away region 
as long as the mouse location remains inside it and unhighlighting it when the mouse 
moves outside it 

TrackZoom 

Tracks the mouse until the mouse button is released, highlighting the zoom region as 
long as the mouse location remains inside it and unhighlighting it when the mouse 
moves outside it 

TaskMaster 

Calls GetNextEvent and looks in the event part of the task record to see if it can 


handle the event 
Window sizing and positioning routines 

MoveWindow Moves a specified window to another part of the screen without affecting its size 


Size Window 

Enlarges or shrinks the port rectangle of a specified window's GrafPort to a specified 
width and height 

ZoomWindow 

Switches the size and position of a specified window between its current size and 
position and its maximum size 

WindDragRect 

Pulls a dotted outline of a specified rectangle around the screen, following the 


movements of the mouse until the mouse button is released 
Update region routines 


InvalRect 

Accumulates a specified rectangle into the update region of the window whose 
GrafPort is the current port 

InvalRgn 

Accumulates a specified region into the update region of the window whose GrafPort 
is the current port 

ValidRect 

Removes a specified rectangle from the update region of the window whose GrafPort 
is the current port and tells the Window Manager to cancel any updates accumulated 
for that rectangle 

ValidRgn 

Removes a specified region from the update region of the window whose GrafPort is 
the current port and tells the Window Manager to cancel any updates accumulated 
for that region 

BeginUpdate 

Replaces the visible region of the window's GrafPort with the intersection of the 
visible region and the update region and then sets the window's update region to an 
empty region 

EndUpdate 

Restores the normal visible region of a specified window's GrafPort that was changed 
by a BeginUpdate call 


Miscellaneous routines 

PinRect Pins a specified point inside a specified rectangle 


CheckUpdate 

Looks from top to bottom in the window list for a visible window that needs updating 
(that is, for a window whose update region is not empty) 
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Window frames and controls 

There are two kinds of predefined window frames, document and alert. The alert 
window is used by the Dialog Manager and is explained in Chapter 6, “Dialog 
Manager,” in Volume 1. The document window, which is used by the Window 
Manager, is explained in this section. The two types of window frames are illustrated 
in Figure 25-2. 


Document window frame Alert window frame 

Figure 25-2 

Window frames 

A document window may have any or all of the standard window controls, as 
listed below. The only restriction is that if there is a close or zoom box there must 
also be a title bar, and common sense would dictate that there only be a zoom box if 
there is a size box, although this is not a requirement. The standard controls include 
the following: 

■ Title bar, a rectangle at the top of the window that contains the window's title, 
may hold the close and zoom boxes, and can be a drag region for moving the 
window 

■ Close box, a small region in the title bar that the user can select to remove the 
window from the saeen 

■ Zoom box, a small region in the title bar that the user can select to make the 
window its maximum size and to return it to its previous size and position 

■ Right scroll bar, which the user selects to saoll vertically through the data in the 
window 

■ Bottom scroll bar, which the user selects to scroll horizontally through the data 
in the window 

■ Size box, a small region in the lower right corner of the window; the user can drag 
the size box to change the size of the window 

■ Information bar, a place in which an application can display some information 
that won't be affected by the scroll bars 
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These standard controls, which can be used only for document windows and may not 
be added to alert windows, are illustrated in Figure 25-3. 


Title bar 


I 

( --^ 



Bottom scroll bar 


Figure 25-3 

Standard window controls 

Some possible document window combinations are illustrated in Figure 25-4. 
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Figure 25-4 

Sample document windows 


Window frames and controls 
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You can either use the standard window types or create your own window types (see 
the section “Defining Your Own Windows” in this chapter). Some windows—such as 
the window the Dialog Manager creates to display an alert—may be created 
indirectly for you when you use other parts of the Toolbox. Windows created either 
directly or indirectly by an application are collectively called application windows. 
Another class of windows, called system windows, consists of windows in which 
desk accessories are displayed. 

The Window Manager’s main function is to keep track of overlapping windows. You 
can draw in any window without running over onto windows in front of it You can 
move windows to different places on the screen, change their planes (front-to-back 
order), or change their sizes—^all without concern for how the various windows 
overlap. The Window Manager keeps track of any newly exposed areas and provides 
a convenient mechanism with which you can ensure that they are properly redrawn. 

You can also easily set up your application so that mouse actions cause the following 
standard responses inside a document window (or similar responses inside other 
windows): 

■ Clicking anywhere in an inactive window makes it the active window by bringing it 
to the front and highlighting it. 

■ Clicking inside the close box of the active window closes the window. Depending 
on the application, this may mean that the window disappears altogether or that a 
representation of the window (such as an icon) is left on the desktop. 

■ Dragging anywhere inside the title bar of a window (except in a dose or zoom box) 
pulls an outline of the window across the saeen; releasing the mouse button 
moves the window to the new location. If the window isn’t the active window, it 
becomes the active window unless the Apple key was also held down. A window 
can never be moved completely off the screen; by convention, it can’t be moved 
such that the visible area of the title bar is less than four pixels square. 

■ Dragging inside the size box of the active window changes the size of the window. 
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Window regions 

Every window has a content region—the area in which your application draws— 
and a frame region—the outline of the entire window plus any standard window 
controls. Together, the content and frame regions make up the structure region* 

The concent region is bounded by the rectangle you specify when you create the 
window (that is, the rectangle specified in the portRect field of the window’s 
GrafPort). This region is where your application presents information to the user. 

A window may also have any of the following regions within the window frame: 

■ Go-away region, a close box in the active window. Clicking in this region closes 
the window. 

■ Drag region, the title bar. Dragging in this region pulls an outline of the window 
across the screen, moves the window to a new location, and makes it the active 
window (unless it was already the active window or unless the Apple key was held 
down). 

■ Grow region, the size box. Dragging in this region pulls the lower right corner of 
an outline of the window across the screen with the window’s origin fixed, resizes 
the window, and makes it the active window (unless it was already the active window 
or unless the Apple key was held down). 

■ Zoom region, the zoom box in the active window. Clicking in this region toggles 
from the current position and size to a maximum size and back again. 

Clicking in any region of an inactive window makes it the active window. 


Data and content areas and scroll bars 

Windows act like a microfiche machine. What is seen in the window’s content region 
is like what is seen on the viewer. Similarly, the window’s data area is what the 
microfiche is to the viewer. Through the content region, the user can see part of the 
data area unless the content region is large enough to view the entire data area. 

Scroll bars are the devices used for scrolling the data area through the content region 
and showing the relationship between the data area and content region. Because 
scroll bars are handled by ^e Control Manager, the Control Manager must be 
loaded and started up before scroll bars can be used in windows. Hie following 
paragraphs explain how standard window scroll bars act in relationship to windows. 

The scroll bar is like a reduced cross section of the work area. The scroll thumb has 
the same ratio to the page region as the content region has to the data area, as 
illustrated in Figure 25-5. 


Data and content areas and scroll bars 
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Data area 


Content region 
(Data In view) 


Figure 25-5 

Proportional scroll bars 

The size and zoom boxes are used to increase or decrease the amount of the data area 
displayed at one time. When the window is moved, the data area is moved with it so 
the view in the content region remains the same. 


Using the Window Manager 

This section discusses how the Window Manager routines fit into the general flow of 
an application and gives you an idea of which routines you’ll need to use under 
normal circumstances. Each routine is described in detail later in this chapter. 

The Window Manager depends on the presence of the tool sets shown in Table 25-2 
and requires that at least the indicated version of each tool set be present. 


Table 25-2 

Window Manager—other tool sets required 


Tool set 

number 

Tool set 

name 

Minimum version 

needed 

$01 

#01 

Tool Locator 

1.2 

$02 

#02 

Memory Manager 

1.2 

$03 

#03 

Miscellaneous Tool Set 

1.2 

$04 

#04 

QuickDraw n 

1.2 

$06 

#06 

Event Manager 

1.0 
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The first Window Manager call that your application must make is WindStartUp. 

Conversely, when you quit your application, you must make the WindShutDown call. 

Where appropriate in your program, use NewWindow to create any windows you 
need. 

There are two ways to handle user input in relation to windows. You can poll the user 
via TaskMaster, which will handle most events that deal with standard user interfaces 
(see the section “Using TaskMaster” in this chapter). 

If you are not using TaskMaster, you must poll for events by calling GetNextEvent in 
the Event Manager. Whenever your application receives an update event, the 
application should respond as follows: 

1. Call the BeginUpdate routine. This routine temporarily replaces the visible 
region of the window’s GrafPort with the intersection of the visible region and the 
update region. It then clears the update region for that window. 

2. Draw the window contents. 

3. Call the EndUpdate routine to restore the actual visible region. 

Activate events for dialog and alert windows are handled by the Dialog Manager. In 
response to activate or inactivate events for windows created directly by your 
application, you might take actions such as the following: 

■ Inactivate controls in inactive window and activate controls in active windows. 

■ Remove the highlighting or blinking cursor from text being edited when the 
window becomes inactive and restore it when the window becomes active. 

■ Enable or disable a menu or certain menu items appropriately to match what the 
user can do when windows become active or inactive. 

If you are not using TaskMaster and a mouse-down event occurs, the application 
should call FindWindow to see if the button was pressed inside a window. The 
following are results from FindWindow and the standard actions to take: 

■ wInMenuBar: Mouse-down somewhere outside the desktop. If you have not 
subtracted any area from the desktop, there is a good chance the button was 
pressed in the system menu bar. Call the Menu Manager routine MenuSelect. 

■ wInDrag: Mouse-down in a window’s drag region; it may or may not be the active 
window. Call DragWindow. 

■ wInContent: Mouse-down in window’s content region. Call SelectWindow if the 
window is not the active window. Otherwise, handle the event according to your 
application. 

■ wInGoAway: Mouse-down in active window’s go-away region. Call 
TiackGoAway. If the routine returns TRUE, you may want to give the user the 
opportunity to save the window; then call Close Window or Hide Window. 

■ wInZoom: Mouse-down in active window’s zoom region. Call TrackZoom. If 
TrackZoom returns TRUE, call ZoomWindow. 

■ wInGrow: Mouse-down in active window’s grow region. Call GrowWindow. 

Uslrig the Window Manager 
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Using TaskMaster 

TaskMaster is a procedure that can handle many standard functions. When 
TaskMaster is called instead of GetNextEvent; the sequence of events is as follows: 

1. TaskMaster calls GetNextEvent. 

2. If there isn’t an event ready, TaskMaster returns 0. 

If an event is ready, TaskMaster looks at it and tries to handle it. 

3. If Taskmaster can’t handle the event that is ready, it returns the event code to the 
application. The application can handle the event as if it had come from 
GetNextEvent. 

If TaskMaster can handle the event, it calls standard routines to try to complete the 
task. For example, if the user presses the mouse button in an active window’s zoom 
region, TaskMaster detects it, calls TrackZoom, calls Zoom Window (if the user 
actually selects the zoom region), and returns no event. 

Sometimes TaskMaster can handle an event only up to a point. If the user presses the 
mouse in the active window’s content region, TaskMaster detects it but won’t be able 
to go any further, so it returns wInContent, which tells the application the mouse 
button is down in the active window’s content region. 

We provide TaskMaster for two reasons. First, it should help you get an application 
running as quickly as possible and still allow you to take advantage of the standard 
user interface. TaskMaster should be usable by even the most advanced 
applications, although some alternate algorithms may have to be used to get the 
desired results. 

Second, TaskMaster provides upward compatiblity in the years to come. If an 
application is using TaskMaster, a modification to TaskMaster to take advantage of 
some new feature will not adversely affect the application; in fact, your application 
may be using the new feature without any modification on your part! 

When calling TaskMaster, you pass a pointer to a TaskMaster record, TaskRec. The 
beginning of the record is the same as an event record. When TaskMaster calls 
GetNextEvent, it passes the provided pointer so that the event record part of TaskRec 
is set by GetNextEvent. The structure of the task record is shown in Figure 25-6. 
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Offset 

$0 

1 

2 

3 

4 

5 

6 

7 

8 

9 
OA 
OB 
OC 
OD 
OE 
0 F 

10 
11 
12 

13 

14 

15 

16 
17 


Field 


— wmWhat — 


— wmMessage — 


— wmWhen — 


— wmWhere 


— wmModifiers — 


—wmTaskDafa — 


— wmTaskMask — 


Word— From event record, unchanged from GetNextEvent 


Long— From event record, unchanged from GetNextEvent 


Long— From event record, unchanged from GetNextEvent 


Long—From event record, unchanged from GetNextEvent 

Word— From event record, unchanged from GetNextEvent 

Long— Extended portion for TaskMaster 


Long— Mask that telis TaskMaster which functions to ignore (see Figure 25-7) 


Figure 25-6 

TaskMaster's TaskRec (task record) 


The umtaskMask is used by your application to tell TaskMaster about functions you 
would like it to ignore. The umtaskMask is defined as shown in Figure 25-7. 


Using TaskMaster 
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Reserved at the time of publication; set to 0 131130| 29| 28| 27) 26| 25l 24| 23| 22| 211 TC/j 19| ISll/l 16 


15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 


tminfo 

Don't activate Inactive window on click in info bar = 1 
Activate inactive window on click in info bar = 0 

tmlnactive 

Return wInactMenu when user selects inactive menu Item = 1 

Never return wInactMenu = 0 

tmCRedraw -* 

Redraw controls upon activate event = 1 
Don't redraw controls upon activate event = 0 

fmSpecial -* 

Handle special menu items = 1 
Don't handle special menu Items = 0 

tmScroii 

Enable scrolling and activate Inactive window on click In scroll bar = 1 
Disable scrolling and don't activate window on click In scroll bar = 0 

tmGrow -* 
GrowWIndow called = 1 
GrowWIndow not called = 0 

tmZoom 

TrackZoom called = 1 
TrackZoom not called = 0 


tmClose 

TrackGoAway called = 1 
TrackGoAway not called = 0 


tmContent 

Activate Inactive window on click In content region * 1 
Don't activate Inactive window on click In content region = 0 


fmDragW 

DragWindow called * 1 
DragWIndow not called = 0 


tmSysCifck 

SystemCIIck called = 1 
SystemCIIck not called = 0 


tmOpenDA 
OpenNDA called = 1 
OpenNDA not called = 0 


tmMenuSel 
MenuSelect called = 1 
MenuSelect not called = 0 


tmFIndW-^ 
FIndWIndow called = 1 
FIndWIndow not called = 0 


tmilpdate 

Update events handled = 1 
Update events not handled = 0 


tmMenuKey 
MenuKey called = 1 
MenuKey not called = 0 


Figure 25-7 

The wmfaskMask bit flag 
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Important 

At the time of publication, bits 31-16 must be set to 0. In fact, TaskMaster will 
return an error If they are not. Because these bits will mask off as yet unknown 
features, applications will continue to run even when the new features are 
added. 


Window Manager icon font 

The Standard docximent window definition uses a font to draw the close and zoom 
boxes, and their highlighted states, in a window’s title. If you would like to use 
different icons, you can replace the default font. To replace the icon font, or just to 
get the handle to the current font, call SetWindowIcons. The format of the font is 
shown in Table 25-3. 

Table 25-3 

Window Manager Icon font 


Character Icon 


0 Close box 

1 Highlighted close 

and zoom boxes 

(same character for both) 

2 Zoom box 


Window record 

The Window Manager keeps all the information it requires for its operations on a 
particular window in a window record. The record contains the information the 
Window Manager needs to manage windows. The complete window record is 
accessed directly only by the Window Manager. Your application can directly access 
only the part of the window record illustrated in Figure 25-8. 

Not allowing direct access to the entire window record has advantages and 
disadvantages. Access to window information is slower if calls have to be made to the 
Window Manager. However, the delay could only be measured in milliseconds and 
can’t be seen on the screen. On the plus side, future Window Managers won’t be tied 
to an older, possibly inadequate, record structure. The chances of improving the 
current Window Manager without affecting existing applications and of maintaining 
compatibility across future hardware are greatly improved by allowing the window 
record to change. 


Window record 
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Many Window Manager calls need as input a window pointer that is returned from 
NewWindow. That pointer points to the window's GrafPort. 


Offset 

SO 

1 

2 

3 

4 


Field 


wNexf 


AD 

AE 


BD 

BE 


Cl 

C2 


C6 

C6 


C9 

CA 


CD 

CE 


D1 

D2 



port 1 


wPadding 

— 

wStrucRgn 

— 


— 

— 

— 

wContRgn 



— 

— 

— 

wUpdateRgn 


— 

— 

— 

— 

wConiTols 

— 

— 

— 

— 

— 

wFrameCtrls 

— 


— 

— 

— 

wFrame — 


Long— POINTER to next window In window list 

170 bytes— Window's GrafPort; returned window pointers point to this 

16 bytes— Reserved for future use 

Long— HANDLE to window's entire region; frame plus content 

Long— HANDLE to window's content region 

Long— HANDLE to region that needs redrawing 

Long— HANDLE to application's first control In content region 

Long— HANDLE to frame's first control 

Word— Bit flag that defines window 


Figure 25-8 

Window record 


The settings for the tvFrame parameter are described in the section “NewWindow” in 
this chapter. 
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Windows and GrafPorts 

It's easy for yoixr application to use windows; to the application, a window is a 
GrafPort the application can draw into with QuickDraw II routines. When you create a 
window, you specify a RECT data structure that becomes the port rectangle of the 
GrafPort in which the window contents will be drawn. The bit map for this GrafPort, 
its pen pattern, and other characteristics are the same as the default values set by 
QuickDraw II. These characteristics apply whenever the application draws in the 
window, and they can easily be changed with QuickDraw II routines. 

There is, however, more to a window than just the GrafPort in which the application 
draws. The other part of a window is called the window frame because it usually 
surrounds the rest of the window. For drawing window frames, the Window Manager 
creates a GrafPort that has the entire screen as its port rectangle. 


Window frame colors and patterns 

In addition to the standard window types and controls, the color of the window and 
controls can be selected. Each 4-bit color is an index into either the default color 
table or a color table pointed to by the wColor field in the NewWindow parameter list 
(see Table 25-8 in the section “NewWindow” in this chapter). See Chapter l6, 
“QuickDraw II,” for more information about color tables. 

The color table for document and alert windows is shown in Figure 25-9. 


Offset Field 

Word— Color of window frame and alert frame 
Bits 15-8 * 0 Bits 7-4 = Outline color 
Bits 3-0 = 0 

Woid— Color of Inactive title bar. Inactive title, and active title 

Bits 15-12 = 0 Bits 11 -8 = Inactive title bar color 

Bits 7-4 = Inactive title color Bits 3-0 = Color of title, close, and zoom boxes 
Word— Color and pattern of title bar 

Bits 15-8 = $0000 = Solid, SOOOl = Dither, $0002 = Lined Bits 7-4 = Pattern color 
Bits 3-0 = Background color 

Word— Color of size box and alert frame's middle outline 

Bits 15-12 = Color of alert frame's middle outline Bits 11 -8 = 0 

Bits 7-4 = Interior color of size box when not selected Bits 3-0 = Interior color of size box when selected 
Word— Color of Information bar ond alert frame's inside outline 

Bits 15-12 = Color of alert frame's inside outline Bits 11 -8 = 0 

7-4 = Interior color of information bar Bits 3-0 = 0 


Figure 25-9 

Document and alert window color table 



Window frame colors and patterns 
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Figures 25-10 through 25-14 show how these colors are used. 



Flaure 25-10 

Window frame color {frameColor) 


Title 


15 

14 

13 

12 

11 

10 

9 

8 1 



0 Background Foreground 


color of 
title's text 
and title 
bar when 
inactive 


color of 
title's text 
when 
Inactive 


Figure 25-11 

Window title color {titleColor) 


3 2 10 


Foreground 
color of 
title, close, 
and zoom 
boxes when 
active 
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Fiaure 25-12 

Window title bar color (.tBarColoT) 


Alert window 




Color of 0 Interior Interior 

alert frame's color when color when 

middle not selected selected 

outline i 


Fiaure 25-13 

Window size box and alert window's middle outline color (growColor) 


Window frame colors and patterns 26-19 
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-li— 






15 

14 

13 

12 

11 

10 

9 

8 

’^7 

6" 



3 

2 


L 


"I— 

Color of 
alert frame's 
inside outline 


Interior 

color 


Alert window 

Flaure 25-14 

Whdow Infornnatlon bar and alert window's Inside outline coior {infoColor) 


Use the SetFrameColor routine to set the color table a window should use and the 
GetFrameColor routine to get a pointer to the window's current color table. 


How a window is drawn 

When a window is drawn or redrawn, the window frame is drawn first, followed by the 
window contents. 

To draw the window frame, the Window Manager manipulates regions of the Window 
Manager port as necessary to ensure that only what should be drawn is drawn. It then 
calls the window definition procedure with a request that the window frame be drawn. 
The window definition procedure is either within the Window Manager or in the 
application for custom windows (see the section “Defining Your Own Windows” in 
this chapter). 

To draw the window contents, the Window Manager generates an update event. 
Whenever your application receives an update event, the application should 
respond as follows: 

1. Call the BeginUpdate routine. This routine temporarily replaces the visible 
region of the window's GrafPort with the intersection of the visible region and the 
update region. It then clears the update region for that window. 

2. Draw the window contents. 

3. Call the EndUpdate routine to restore the actual visible region. 

Update events are issued for the frontmost window first and the hindmost last. 
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Draw content routine 

When the NewWindow call is used to open a new window, the Window Manager 
checks the wContDefProc field. If that field is nonzero, the value is considered to be 
the address of a routine in your application that will draw the window’s content 
region. 

The wContDeJProc field must be set if you want to use window frame scroll bars 
(which are the scroll bars TaskMaster creates). TaskMaster will scroll the content and 
call wCorUDefProc to update the uncovered area when the user performs a scrolling 
action. wContDefProc could be considered a control action procedure. 

The wContDeJProc field might be useful even if you are not using window frame scroll 
bars. TaskMaster can handle your update events if wContDefProc is set TaskMaster 
will call BeginUpdate, wContDefProc, and EndUpdate. 

There are no inputs or outputs to your draw content routine. 

❖ Note: Use the QuickDraw II routine GetPort to obtain the current window 
pointer. 

Draw what is needed in the content and perform an RTL to exit. Remember that the 
content will have already been erased using the window port’s background pattern 
and that the visible region is set to the area needing to be redrawn. 


Warning 

Do not change ports or perform a QuickDraw II SetOrigIn call while In your draw 
content routine. 


Draw information bar routine 

If the finfo bit (bit 4) is set to 1 in the wFrameBits field of the NewWindow parameter 
list, the window will have an information bar that appears just above the content 
region. The width of the information bar is same as the width of the window, and the 
height of the information bar is specified by the wInfoHeight field in the 
NewWindow parameter list. 

The Window Manager draws the information bar, but it is up to the application to 
draw any information inside the bar. Your application can do this by storing the 
address of a draw information bar routine in the wInfoDefProc field of the 
NewWindow parameter list (and you must also set the finfo bit of wFrame), When 
the standard window frame definition procedure draws the empty information bar, it 
will also call the procedure pointed to by wInfoDefProc, 


How a window Is drawn 
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TTie inputs to your routine will be as follows: 


Long—^POINTER to RECT data structure specifying enclosing rectangle 

Long —wlnfoRefCon value from NewWindow parameter list 

Long—POINTER to window’s GrafPort 
3 bytes—RTL address 

An assembly-language example of a draw information bar routine that prints a string 
looks like this: 


InfoDefProc 

START 




theWindow 

equ 

6 



InfoData 

equ 

theWindow+4 



InfoBar 

equ 

InfoData+4 




phd 


f 

Save the current direct page 


tsc 





ted 


f 

Switch to direct page in stack 

; - Position 

the pen at the text 

starting point-; 


Idy 

#left_side 

f 

(Where left_side equals 2) 


Ida 

[InfoBar],y 

r 

Get the left side of the information bar. 


clc 





adc 

#20 

! 

plus a tab over, to get 


pha 


r 

a starting X position (pass to _MoveTo) 

f 

Idy 

#top_side 

r 

(Where top_side equals 0) 


Ida 

[InfoBar],y 

t 

Get the top side of the information bar. 


clc 





adc 

#10 

• 

t 

plus enough to vertically center the text, to 


pha 


t 

get a starting Y position (pass to _MoveTo) 


_MoveTo ; Move the pen to the starting point. 
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infoBarPtr 


infoData 


— theWindowPtr 

im I m 

m <— SP 




.e text 

on the information 

bar - 


pea 

infoStrg|-16 

r 

Pass high word of string 

pea 

infoStrg 

9 

Pass low word of string 

^Drawstring 

9 

Print the string 

1 , now 

clean up stack and 

return to Window Manager-; 

ply 


9 

Get original direct page back 

Ida 

2,s 

9 

Move return down over input parameters 

sta 

<14 

9 

Works because stack and direct page are equal 

Ida 

0, s 



sta 

<12 



tsc 


9 

Now move stack pointer over input parameters 

clc 




adc 

#12 

9 

Number of bytes of input parameters 

tcs 


9 

New stack 

tya 


* 

9 

Restore original direct page 

ted 




rtl 


9 

Back to Window Manager 

dc 

i*8\c*MyTitle* 



END 





infoStrg 


The example takes some liberties, such as assuming the color and writing mode of the 
pen when the text is written. When entered, the current port is the Window 
Manager’s. You may change the pen location, color, and writing mode without 
saving the original port state. However, that’s as much as you should do without first 
saving the port state and then restoring it on exit. 

Another liberty the example takes is when the text is centered vertically. You should 
make QuickDraw calls to find font height, to find the InfoBar height, and then to 
actually center the text. You should always use InfoBar as offsets into the information 
bar interior because the height could be different from time to time. 


Important 

Do not change the current port's cllpRgn or vIsRgn fields unless you save and 
restore the original value. 


How a window 1$ drawn 
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Making a window active: activate events 

A number of Window Manager routines change the state of a window from inactive to 
active or from active to inactive. For each such change, the Window Manager 
generates an activate event, passing along the window pointer in the event message. 
The activeFlag bit in the modifiers field of the event record is set if the window has 
become active; it is cleared if it has become inactive. 

When the Event Manager finds out from the Window Manager that an activate event 
has been generated, it passes the event on to the application (via the GetNextEvent 
function). Activate events have the highest priority of any type of event. 

Usually when one window becomes active another becomes inactive and vice versa, 
so activate events are most commonly generated in pairs. When this happens, the 
Window Manager generates first the event for the window becoming inactive and 
then the event for the window becoming active. Sometimes only a single activate 
event is generated—^such as when there's only one window in the window list or when 
the active window is permanently discarded (because it no longer exists). 

Activate events for dialog and alert windows are handled by the Dialog Manager. In 
response to activate or inactivate events for windows created directly by your 
application, you might take actions such as the following: 

■ Inactivate controls in inactive window and activate controls in active windows. 

■ Remove the highlighting or blinking cursor from text being edited when the 
window becomes inactive and restore it when the window becomes active. 

■ Enable or disable a menu or certain menu items to match what the user can do 
when windows become active or inactive. 
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Defining your own windows 

You may want to define your own type of window, such as a round or hexagonal 
window; QuickDraw and the Window Manager allow you to define your own window 
shape. 

To define your own type of window, you must write a window definition procedure 
that defines the appearance and behavior of the window. Then, when the Window 
Manager needs to do something, it calls your routine and not its own. 

You pass the address to the NewWindow call in the wFrameDeJProc parameter (see 
the section “NewWindow” in this chapter). The inputs to your routine are 

Stack before call 


Word—Operation to be performed 
Long— POINTER to window’s GrafPort 


Long—Parameters used by some messages 
<—SP 


previous contents 
varCode 


— theWindowPtr 


params 


Stack after call 
previous contents 

— outcomeFlag — Long—Returned parameter flag 

<— SP 

The varCode parameters are shown in Table 25-4. 

Table 25-4 

The varCode parameters for custom windows 


Value Name Description 


0 

1 

2 

3 

4 

5 


wDraw 

wHit 

wCalcRgns 

wNew 

wDispose 

wGrow 


Draw window frame 
Tell what region the cursor was in 
when the mouse button was pressed 
Calculate wStructPgn and wContRgn 
Do any additional window initialization 
Take any additional disposal actions 
Draw window’s grow image 


Defining your own windows 
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What you can expect in response to each of the codes is desaibed immediately 
following the wContDeJProc example. 

Your routine must strip off the three input parameters and return via RTL. So the 
shell of your wContDejProc routine might be as follows: 


MyWindow 

START 




Ida 

12,s 

; Get varCode 


asl 

a 



tax 




Ida 

>actions, X 



pha 




rts 


; Go to action handler 

actions 

dc 

i2'draw_wind-l' 

; Routine to draw window's frame 


dc 

i2'test_hit-l' 

; Routine to find a window region 




; at a given point 


dc 

i2'calc_rgns-l' 

; Compute window's wStructRgn and wContRgn 


dc 

i2'init_wind-l' 

; Do additional initialization 


dc 

i2'kill_wind-l' 

; Do additional disposal 


END 



draw_wind 

START 




<code 

that draws window 

frame) 


jmp 

exit 



END 



test_hit 

START 




(code 

that finds area of 

the window in which the point in params is located) 


jmp 

exit 



END 



calc_rgns 

START 




(code 

that computes the 

window's wStructRgn and wContRgn) 


jmp 

exit 



END 
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init_wind 

START 




(code 

that performs additional 

initialization) 


jmp 

exit 



END 



ki Unwind 

START 




(code 

that performs additional disposal) 


jmp 

exit 



END 



exit 

START 




Ida 

2 f s / 

Move return address 


St a 

12,s 



Ida 

l,s 



sta 

11,s 



tsc 


Strip off input parameters 


sec 




sbc 

#10 



tcs 




rtl 

t 

Return to Window Manager 


END 



wDraw: draw a window frame 


Your routine should draw in the current GrafPort, which will be the Window Manager 
port. The Window Manager will request this operation only if the window is visible. 


The structure of the params parameter is as follows: 


wDrawFraine 


wInGoAway 


wInZoom 

Bit 31 


$00 Draw window^s entire frame. 

$ 01 Draw go-away region. 

$02 Draw zoom region. 

1 Draw frame or region as highlighted. 

0 Draw frame or region as unhighlighted. 


Thus, valid params values are as follows: 


$00000000 

$80000000 

$00000001 

$80000001 

$00000002 

$80000002 


Draw entire window frame as an inactive window. 
Draw entire window frame as an active window. 
Draw go-away region as unhighlighted. 

Draw go-away region as highlighted. 

Draw zoom region as unhighlighted. 

Draw zoom region as highlighted. 
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wHit: find what region a point is in 

The params parameter specifies the point to check. The vertical coordinate is in the 
low-order word and the horizontal coordinate in the high-order word. The Window 
Manager requests this operation only if the window is visible. Your routine should 
determine where the point is in your window and then return one of the following: 


wNoHit 

0 

Not on the window at all 

winContent 

19 

In window's content region 

wInDrag 

20 

In window's drag (title bar) region 

wInGrow 

21 

In window's size box region 

wInGoAway 

22 

In window’s go-away (close box) region 

winZoom 

23 

In window's zoom (zoom box) region 

wininfo 

24 

In window’s information bar 

wInFrame 

27 

In window, but not in any of the above areas 

Usually, wNoHit means 

the given point isn't anywhere within the window, but this is 


not necessarily so. 


wCalcRgns: calculate a window’s regions 

Your routine should calculate the window’s entire region, place it in the wStrucRgn, 
and place the content region in wContRgn based on the current GrafPort’s port 
rectangle. The Window Manager requests this operation only if the window is visible. 


Warning 

When you calculate regions for your window, do not alter the cllpRgn or visRgn 
fields of the window's GrafPort. 


wNew: perform additional initialization 

After initializing fields appropriately when creating a new window, the Window 
Manager sends the message wNew to your routine. This gives your routine a chance 
to perform any initialization it may require. For example, because the structure of 
the window record is not documented, you may want to allocate your own record 
structure, initialize it, and store its pointer via a SetWRefCon call. 
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wDi$po$e: remove a window 

The Window Manager’s Close Window and DisposeWindow procedures send this 
message so your routine can carry out any additional actions required when 
disposing of the window. The routine might, for example, release space that was 
allocated by the initialize routine. The routine is called before all controls in the 
wControls and wFrameCtrls lists are removed via a KillControls call to the Control 
Manager, the port is closed, and the window record freed. Return 0 to continue 
closing or 1 to abort closing. 


wGrow: draw the outline of a window 

The params parameter is a pointer to a RECT data structure defining a rectangle. 
Your routine should draw an outline image of your window that would fit the specified 
rectangle. The Window Manager requests this operation repeatedly as the user drags 
inside the grow region. Your routine should use the GrafPort’s current pen pattern 
and pen mode. 


Origin movement 

This section describes in detail how the origin of a window can change and what the 
effects of that change are. To benefit from the following discussion, you should 
already be familiar with QuickDraw II’s explanation of ports and boundsRect. 

The origin of a window is what allows data to be scrolled and drawing to occur in the 
proper place after a scroll. In Figure 25-15, the gray area is a screen with the pixel in 
its upper left corner being 0,0 (coordinates are shown here as Y,X3. The window port 
appears on the screen at 65,50 to 85,80. These points are called global coordinates* 
To draw the house, the X coordinate of the left side would be 60; that is, it would be 10 
pixels inside the window port 

0 50 



Figure 25-15 

Window origin 

Origin movement 
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However, a window port has its own coordinates, called local coordinates. Figure 
25-16 shows what really happens when a window is created. Although the window is 
still at 65,50 to 85,80 on the screen, the local coordinates of the window are 0,0 to 
20,30. Notice that the window’s height and width remain the same. Also notice that 
the window is now called the port rectangle and the screen the bounds rectangle. 

To draw the left wall of this house, you would pass the X coordinate of 10 to 
QuickDraw n to draw a single vertical line. QuickDraw II would then subtract the X 
origin of the boundsRect to determine where on the screen to actually draw the line. 
So, 10 minus -50 is 60. The global coordinate is 6O; the local was 10. You will always 
work with local coordinates; that way, if the window is moved, its coordinate system 
remains the same. This explains what happens to the horizontal axis; the same thing 
happens with the vertical axis. 

The Window Manager changes the coordinates of the bounds rectangle when the 
window is moved. If the window is moved one pixel to the left, the boundsRect would 
become -65,-49. When the coordinate of 10 is passed to QuickDraw II, it computes 
the global coordinate of 59 (10 minus -49). Thus, even though the house is drawn on 
another place on the screen, it is drawn in the same place in the window, and the 
application doesn’t have to make any changes. 


-50 0 10 



Figure 25-16 

Window moving and origins 
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In the previous simple examples, everything had origins of 0,0. However, one of the 
powerftil features of windows is their ability to saoU to show more data than the 
screen allows. In the next example, the window has not moved, but the user has 
saolled the picture using the bottom scroll bar (see Figure 25-17). When the user 
moved the thumb on the scroll bar, the rectangle (0,10,20,30) was scrolled (moved) 
to (0,0,20,20). Then the origin of the window was changed to 0,10, and the exposed 
rectangle on the right side was redrawn in an update event 

After the scrolling occurred, the application would pass the coordinate of 10 to draw 
the left side of the house and QuidcDraw II would compute 10 minus -40 to get the 
global coordinate of 50. Now, a minor problem arises; the Window Manager needs 
every window to have an origin of 0,0 for it to move, grow, and overlap windows. 

This feature may eventually change, but for now, whenever the Window Manager is 
called, the origin of every window must be 0,0. 



Figure 25-17 

Scrolling and window origins 


For example, whenever TaskMaster calls your update routine, it switches to the 
window’s port and sets its origin; in this example it would be SetOrigin(0,10). Then 
you can draw in the window’s local coordinates. When you have finished drawing 
and return to TaskMaster it performs a SetOrigin(0,0). 

Even though changing the origin does not change the screen, any drawing outside of 
your update routine without setting the origin would have undesirable results. 

Drawing your house with the origin still at 0,0 would produce two houses, one shifted 
10 pixels to the right of the other. To draw outside of your update routine, you need 
to first set the origin either yourself or through a StartDrawing call and then perform a 
SetOrigin(0,0) to put it back. 

In short, when drawing outside of your update routine, you must perform a 
StartDrawing call before drawing and a SetOrigin(0,0) when you are finished 
drawing. This is also true when you ate performing a hit test in your content region; 
the event position must be converted to local coordinates. 


Origin movement 
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$01OE WindBootInit 

Initializes the Window Manager; called only by the Tool Locator. 


Warning 

An application must never make this call. 


Parameters The stack is not affected by this call. There are no input or output parameters. 

Errors None 

C Call must not be made by an application. 

$020E WindStartUp 

Starts up the Window Manager for use by an application. 

Important 

Your application must make this call before it makes any other Window Manager 
calls. 

Parameters 

Stack before call 

previous contents 

userlD Word—ID number of application 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void WindStartUp(userlD) 

Word userlD; 
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$030E WindShutDown 

Shuts down the Window Manager down when an application quits. 


Important 

If your application has started up the Window Manager, the application must 
make this call before it quits. 


Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C extern pascal void WindShutDown() 


$040E WindVersion 

Returns the version number of the Window Manager. 

Parameters 

Stack before call 

previous contents 

wordspace Word—Space for result 

<—SP 


Stack after call 
previous contents 

versioninfo Word—^Version number of Window Manager 

<—SP 

Errors None 

C extern pascal Word WindVersion() 
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$050E WindReset 

Resets the Window Manager, called only when the system is reset. 

Warning 

An application must never make this call. 

Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C Call must not be made by an application. 


$060E WindStatus 

Indicates whether the Window Manager is active. 

Parameters 

Stack before call 
previous contents 

tvordspace Word—Space for result 

<—SP 


Stack after call 
previous contents 

activeFlag Word—BOOLEAN; TRUE if Window Manager active, FALSE if inactive 

<—SP 

Errors None 

C extern pascal Boolean WindStatus() 
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$1E0E Beginllpdate 

Replaces the visible region of the window’s GrafPort with the intersection of the visible 
region and the update region and then sets the window’s update region to an empty 
region. 

Call BeginUpdate when an update event occurs for the window. You would then 
usually draw the entire content region, although it suffices to draw only the visible 
region. In either case, only the parts of the window that require updating and are 
visible will actually be drawn on the screen. Every call to BeginUpdate must be 
balanced by a call to the EndUpdate routine, as follows: 

1. Call BeginUpdate. 

2. Draw the window contents. 

3. Call the EndUpdate routine to restore the actual visible region. 


Parameters 

Stack before call 
previous contents 

— theWindotvPtr — Long— pointer to window’s GrafPort 

SP 


Stack after call 
I previous contents 


^SP 


Errors None 


C 


extern pascal void BeginUpdate(theWlndowPtr) 
GrafPortPtr theWindowPtr; 
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$240E BringToFront 

Brings a specified window to the front of all other windows and redraws the windows as 
necessary but does not do any highlighting or unhighlighting. Normally you won’t 
have to call this procedure; you should call SelectWindow to make a window active, 
and SelectWindow takes care of bringing the window to the front. If you do call 
BringToFront, however, remember to call HiliteWindow to make any necessary 
highlighting changes. 


Parameters 

Stack before call 

previous contents 

— theWindowPtr — Long—POINTER to window’s GrafPort 

<—SP 


Stack after call 


previous contents 


SP 


Errors None 


C 


extern pascal void BringToFront(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$OAOE CheckUpdate 

Looks from top to bottom in the window list for a visible window that needs updating 
(that is, for a window whose update region is not empty). CheckUpdate is normally 
called only by the Event Manager, and doesn’t need to be called by an application. 

If a window with something in its update region is found, an update event for that 
window is stored in the event and the routine returns TRUE. If it doesn’t find such a 
window, it returns FALSE. 


Parameters 


Stack before call 


previous contents 


wordspace 


theEventPtr 

— 


Word—Space for result 
Long—POINTER to an event record 
<— SP 


Stack after call 
previous contents 

updateFlag Word—^BOOLEAN; TRUE if update event found, otherwise FALSE 

<— SP 

Errors None 

C extern pascal Boolean CheckUpdate<theEventPtr) 

EventRecordPtr theEventPtr; 
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$OBOE CloseWindow 

Removes a specified window from the screen, disposes of all controls associated with 
that window, and deletes the window from the window list. The routine releases the 
memory occupied by all data stmctures associated with the window, including the 
memory taken up by the window record if it was allocated by NewWindow. Call this 
routine when you’re done with a window. 

Any update events for the window are discarded. If the deleted window was the 
frontmost window, the window behind it (if any) is highlighted and an appropriate 
activate event is generated. 


Warning 

If you allocated memory yourself and stored a handle to it In the wRefCon field, 
CloseWindow won't know about it—you must release the memory before calling 
CloseWindow, 


Parameters 

Stack before call 
previous contents 

— theWindowPtr — Long—POINTER to window’s GrafPort 

SP 


Stack after call 
I previous contents 


SP 


Errors None 


C 


extern pascal void CloseWindow(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$OCOE Desktop 

Controls the addition of regions to and subtraction of regions from the desktop and 
controls the current desktop pattern. The values for the deskTopOp and dtParam 
parameters are shown in Table 25-5. 

Parameters 


Stack before call 
previous contents 
longspace 
deskTopOP 
dtParam 


Long—Space for result if necessary 
Word—Operation to perform 
Long—Parameter needed for operation 
<—SP 


Stack after call 


previous contents 


retParam 


Long—Possible return parameter (see Table 25-5) 
<—SP 


Errors None 

C extern pascal Pointer DesktoptdeskTopOP,dtParam) 

Word deskTopOP; 

LongWord dtParam; 

(continued) 
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Table 25-5 

Window Manager Desktop routine operations and parameters 


Operation 


FromDesk 


ToDesk 


GetDesktop 


Operation 

number Description and dtParam and retParam values 

0 Subtract region from desktop region. 

dtParam —handle to region to be subtracted 
retParam—^oi used 

The region passed in dtParam will be subtraaed from the current 
desktop region. When the Window Manager redraws the desktop, it 
will not draw the region subtracted. Windows will not cover the 
subtracted region and will appear to move underneath the region. 
For example, the Menu Manager subtracts a region from the desktop 
for the system menu bar, which is why windows move under the 
system menu bar. 

FromDesk can be called repeatedly to remove additional areas 
from the desktop. 

1 Add region to current desktop region. 

dtParam —HANDLE to region to be added 
retParam —Not used 

When the Window Manager redraws the desktop, it will also draw the 
region added. ToDesk can be called repeatedly to add additional 
areas to the desktop. 

2 Return handle to current desktop region. 

dtParam —Not used 

retParam —HANDLE to desktop region 

The handle returned is the actual handle to the desktop region; any 
modifications to this region will change the desktop. Using the 
handle, you can add, subtract, or XOR a region; find intersections; 
and perform other region operations. This call can also be used for 
restoring the desktop to its original shape after modifying it for 
some temporary use (see SetDesktop for restoring the desktop). 


Warning 

Do not free the handle of the desktop region; that will cause 
the Window Manager to crash. 
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Table 25-5 (continued) 

Window Manager Desktop routine operations and parameters 


Operation 


SetDesktop 


GetDeskPat 


SetDeskPat 


GetVisDesktop 


Operation 

number Description and dtParam and rotParam values 

3 Set handle to desktop region. 

dtParam —^HANDLE to new desktop region 
retParam —Same as param 

After SetDesktop is called, the new handle will be used by the 
Window Manager for the handle of the desktop region. It is not 
necessary to call SetDesktop if you have called GetDesktop and 
modified the region because GetDesktop returns the actual 
desktop handle. 


Warning 

SetDesktop overwrites the current desktop region handle. 
Therefore, It is up to the application to free the original handle 
or save It and restore It later. 


4 Return current desktop pattern. 
dtParam —Not used 

retParam —Current desktop pattern (see Table 25-6) 

GetDeskPat returns information about how the desktop is being 
drawa There are several ways the desktop can be drawn, as shown 
in Table 25-6. 

5 Set new desktop pattern. The desktop is redrawn with the new 
pattern. 

rf/Param—New desktop pattern (see Table 25-6) 
retParam— used 

SetDeskPat changes how the desktop is drawn. There are several 
ways the desktop can be drawn, as specified in Table 25-6. 

6 Return desktop, less any windows. 

dtParam —^Handle to region that will be set to the visible desktop 
retParam —^Not used 

The current desktop region minus any visible windows is copied into 
the given region. The visible desktop can be used for drawing on the 
desktop. See the following discussion of BackGroundRgn for an 
extension to GetVisDesktop. 


(continued) 
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Tablo 25-5 (continued) 

Window Manager Desktop routine operations and parameters 


Operation 


BackGroundRgn 


Operation 

number 


7 


Description and dtParam and retParam values 


Maintain visible desktop region. 

dtParam —Handle to a region 
retParam —Not used 

The region passed will be set to the desktop region less any windows. 
The region is automatically updated when windows are added, 
removed, sized, and moved. This operation provides applications 
an easy way of drawing objects directly on the desktop. A possible 
sequence for drawing objects on the desktop might be as follows: 


pha 

pha 

pea SetDeskPat 

pea MyDeskDraw|-16 

pea MyDeskDraw 

__Desktop 

pla 

pla 

pea MyDeskPortI-16 
pea MyDeskPort 
_OpenPort 
pha 


pha 

pea 

Ida 


BackGroundRgn 
MyDeskPort+VisRgn+2 


pha 

Ida MyDeskPorttVisRgn 

pha 

_Desktop 

pla 

pla 


; Space for result (not used) 

; Operation number 5 

/ Pass address of my routine 
; that will draw the desktop 

; Result not used 

; Open a port for my desktop 

; Space for result (not used) 

/ Operation number 7 

; Pass handle of my desktop 
; port's visRgn 


Result not used 
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Table 25-5 (continued) 

Window Manager Desktop routine operations and parameters 


Operation 

Operation number Description and dtParam and retParam values 

After this code is executed, the routine MyDeskDraw will be called 
by the Window Manager whenever the desktop needs to be drawn. 

The preceding code passed the value of the vision field of a port to 
the Window Manager. The Window Manager will use that value to 
compute the visible desktop. Then, when an application wants to 
draw an object on the desktop, it can switch to MyDeskPort and 
draw. All drawing will be clipped to the current visible desktop. 

❖ Note: The address of the routine passed to the Desktop routine 
for operation SetDeskPat (operation 5) is still a routine that is 
called with the current port being the Window Manager’s with its 
clip region set to the visible desktop. To draw whenever you want, 
you’ll have to use your own port and your own visible region. 


Desktop patterns 

There are no inputs to or outputs from the routine called to draw the desktop. The 
current port will be the Window Manager’s, and the clipping region will be set to the 
area needing to be drawn. Your routine should exit via an RTL. 


Warning 

The current direct page and data bank are not defined on entry to your routine. 
When you exit your routine, the direct page and data bank must be the same 
as they were on entry. 


The desktop pattern is determined by a long value, as shown in Table 25-6. 

Table 25-6 
Desktop patterns 


Byte 1 Byte 2 Byte 3 Byte 4 

$00 Address of routine that will be called to draw desktop 

$80 Address of pattern to be used for desktop (see Chapter l6, “QuickDraw 11”) 

$40 00 00 = Solid desktop pattern High nibble = Pattern’s foreground color 

01 = Dithered desktop pattern Low nibble = Pattern’s background color 
02 = Horizontally striped 
desktop pattern 
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$1A0E DragWindow 

Pulls around a dotted outline of a specified window, following the movements of the 
mouse until the mouse button is released. When the button is released, DragWindow 
calls MoveWindow to move the specified window to the location to which it was 
dragged. The window will be dragged and moved in its current plane. 

When there is a mouse-down event in the drag region of the specified window and 
TaskMaster is not being used, the application should call DragWindow with startY, 
startX equal to the point where the mouse button was pressed (in global coordinates, 
as stored in the where field of the event record). 


Parameters 


Stack before call 


previous contents 


grid 


StartX 


StartY 


grace 


— boundsRectPtr — 


— theWindowPtr 


Stack after call 


Word —^Drag resolution, zero for default (see Table 25-7) 

Word —Starting X coordinate of cursor, in global coordinates 
Word —Starting Y coordinate of cursor, in global coordinates 
Word —Grace buffer around bounds 

Long —POINTER to RECT Structure for cursor boundary, NIL for default 

Long —POINTER to window’s GrafPort 
<—SP 


previous contents I 

K—SP 


Errors None 


C extern pascal void DragWlndowIgrid,startX,startY,grace,boundsRectPtr, 

theWindowPtr) 

Word grid; 

Integer startX; 

Integer startY; 

Word grace; 

Rect *boundsRectPtr; 

GrafPortPtr theWindowPtr; 
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You can also use the following alternate form of the call: 

extern pascal void DragWindow(grid,start,grace,boundsRectPtr,theWindowPtr) 
Word grid; 

Point start; 

Word grace; 

Rect *boundsRectPtr; 

GrafPortPtr theWindowPtr; 


Parameter description 

grid The allowed horizontal resolution movement, as shown in 

Table 25-7. The parameter is provided to speed up window 
moves by eliminating the need for bit shifting, if the gr/rf value 
is the correct value. If grid is passed as 0, a default value will be 
used. The defaults are 4 for 320 mode and 8 for 640 mode. The 
only allowed values are 1, 2, 4, 8, l6, 32, 64, 128, and so on. 

Table 25-7 

DragWIndow grid values 
Value Window movement 
0 Default value used. 

1 Window can be positioned at any horizontal position. 

2 Window can only be moved a multiple of 2 pixels 

horizontally. 

4 Window can only be moved a multiple of 4 pixels 

horizontally. 

8 Window can only be moved a multiple of 8 pixels 

horizontally. 

startY and startX Indicate where the mouse button was pressed, in global 

coordinates, as stored in the where field of the event record. 
This point is used with the tracked cursor position to compute 
the movement delta. 


(continued) 
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grace 


boundsRectPtr 


The distance, in pixels, that you will allow the cursor to move 
away from the bounds rectangle before the dragged outline 
should be snapped back to its starting position. TaskMaster 
uses 8 for this value. The bounds rectangle is expanded by the 
value of grace to compute the slop rectangle that is passed to 
DragRect as the slopRect parameter. See the section 
“DragRect” in Chapter 4, “Control Manager,” in Volume 1 for 
more information. 

Pointer to a RECT data structure, in global coordinates, that is 
passed to DragRect as the limitRect parameter. See the section 
“DragRect” in Chapter 4, “Control Manager,” in Volume 1 for 
more information. If NIL is passed for the pointer, the bounds 
of the desktop, minus 4 all around, will be used. 
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$510E EndinfoDrawing 

Puts the Window Manager back into a global coordinate system. Call this routine after 
a StartInfoDrawing call and before any other calls to the Window Manager. 


Warning 

Calling any Window MarKiger routine between a StartlnfoDra\Adng call and an 
EndinfoDrawing call may result In system failure. 


Parameters The stack is not affected by this call. There are no input or output parameters. 
Errors None 

C extern pascal void EndinfoDrawing() 


$1F0E EndUpdate 

Restores the normal visible region of a specifed window’s GrafPort that was changed 
by a BeginUpdate call. 

Parameters 

Stack before call 
previous contents 

— theWindowPtr — Long—POINTER to window’s GrafPort 

^SP 


Stack after call 

previous contents I 

<—SP 


Errors None 


C 


extern pascal void EndUpdate(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$170E FindWindow 

Tells which part of which window, if any, the cursor was in when the user pressed the 
mouse button. If it was pressed in a window, the whichWindowPtr pirzraelQT is set to 
the window port pointer, otherwise, it’s set to NIL. 

When a mouse-down event occurs, the application should, if not using TaskMaster, 
call FindWindow with pointX and pointY equal to the point where the cursor was when 
the user pressed the mouse button (in global coordinates, as stored in the where field 
of the event record). 


Parameters 

Stack before call 

Word—Space for result 

Long—POINTER to space to store pointer to window; NIL if not found 

Word—point to check, in global coordinates 
Word—Y point to check, in global coordinates 
<—SP 


previous contents 
wordspace 

— whichWindowPtr — 


pointX 

pointY 


Stack after call 


previous contents 
location 


Word—^Mouse-down event location (see Table 25-8) 
<—SP 


Errors None 

C extern pascal Word FindWindow(whichWindowPtr,pointX,pointY) 

GrafPortPtr *whichWinciowPtr; 

Integer pointX; 

Integer pointY; 

You can also use the following alternate form of the call: 
extern pascal Word FindWindow(whichWindowPtr,point) 
GrafPortPtr *whichWindowPtr; 

Point point; 
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Mouse-down event location information 

The location returned by FindWindow is one of the constants shown in Table 25-8. 


Table 25-8 

FindWindow constants 


Word 

Event 

Description 

$0000 

wNoHit 

Not in the window at all 

$0010 

wInDesk 

In the desktop area 

$0011 

wInMenuBar 

In the system menu bar 

$0013 

wInContent 

In window’s content region 

$0014 

winDrag 

In window’s drag (title bar) region 

$0015 

wInGrow 

In window’s size box region 

$0016 

wInGoAway 

In window’s go-away (dose box) region 

$0017 

winZoom 

In window’s zoom (zoom box) region 

$0018 

wininfo 

In window’s information bar 

$0019 

wInSpecial 

In spedal menu item bar (see Chapter 13, “Menu 
Manager,” in Volume 1) 

$001A 

wInDeskitem 

Desk accessory selected from the Apple menu 

$001B 

winFrame 

In window, but not in any of the areas defined in this 
table 

$001C 

wInactMenu 

Inactive menu item selected 

$8xxx 

wInSysWindow 

In a system window 
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$160E FrontWindow 

Returns a pointer to the first visible window in the window list (that is, the active 
window). If there are no visible windows, the routine returns NIL. 


Parameters 

Stack before call 
previous contents 

longspace — Long —Space for result 

<—SP 


Stack after call 
previous contents 

— theWindowPtr — Long —POINTER to active window’s GrafPort; NIL if none visible 

<—SP 

Errors None 

C extern pascal GrafPortPtr FrontWindow() 
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$4dOE GetContentDraw 

Returns the pointer to the routine that draws the content region of a specified window. 

TaskMaster calls this routine when it gets an update event for that window. See the 
section “Draw Content Routine” in this chapter for more information about the draw 
routine. 

Parameters 


Stack before call 
previous contents 
longspace 


Long—Space for result 


~ theWindowPtr — 


Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 

previous contents 


contentProcPtr 


Long—POINTER to routine called to draw content region 
<—SP 


Errors None 

C extern pascal VoidProcPtr GetContentDraw(theWlndowPtr) 

GrafPortPtr theWindowPtr; 
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$3E0E GetContentOrgin 

Returns the values used by TaskMaster to set the origin of the window’s GrafPort when 
handling an update event. The values are also used to compute scroll bars in the 
window frame. 


Parameters 


Stack before call 
previous contents 
longspace 


Long—Space for result 


— theWindowPtr — 


Long—POINTER to window’s GrafPort 


SP 


Stack after call 


previous contents 


origin 


Long—^POINT; low word = Y origin, high word = X origin 
<—SP 


Errors None 

C extern pascal Long GetContentOrigin(theWlndowPtr) 

Pointer theWindowPtr; 

❖ Note: C Pascal-type functions do not deal properly with data structures returned 
on the stack. The Long result returned by this call can be passed to any calls 
requiring a point as a parameter. You cannot use the C dot operator to access the 
individual Y and X coordinates within the value returned by tWs call. 
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$2F0E GetContentRgn 

Returns a handle to a specified window’s content region. See the section “Window 
Regions” in this chapter for a definition of the content region. 

Parameters 


Stack before call 
previous contents 
longspace 


Long—Space for result 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
SP 


Stack after call 

previous contents 
— wContHandle 


Long—HANDLE to window’s content region 
SP 


Errors None 


C 


extern pascal RgnHandle GetContentRgn(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$400E GetDataSIze 

Returns the height and width of the data area of a specified window. The data area is 
the total amount of data that can be viewed in a window through resizing or scrolling. 

Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
SP 


Stack after call 
previous contents 
dataSize 


Long—Low word = height; high word = width 
<—SP 


Errors None 


C 


extern pascal LongWord GetDataSize(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$31OE GetDefProc 

Returns a pointer to the routine that is called to draw, hit test, and otherwise define a 
window’s frame and behavior. 

Parameters 

Stack before call 

Long—Space for result 

Long—POINTER to window’s GrafPort 
<— SP 


previous contents 


longspace 


— theWindowPtr 


Stack after call 
previous contents 


wDefProcPtr 


Errors 

C 


Long—POINTER to window’s definition procedure 
SP 


None 

extern pascal LongProcPtr GetDefProc(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$520E GetFirstWindow 

Returns a pointer to the first window in the Window Manger’s window list. The 
returned window may not be the active window (see the section “FrontWindow” in this 
chapter). Every window in the window list, whether visible or not, can be accessed if 
you call GetFirstWindow and then call the GetNextWindow routine to run down the 
remainder of the window list. 


Parameters 

Stack before call 

previous contents 

longspace — Long—Space for result 

<—SP 


Stack after call 

previous contents 

— firstWindowPtr — Long—^POINTER to first window, or NIL 

SP 

Errors None 

C extern pascal GrafPortPtr GetFirstWindow() 
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$100E GetFrameColor 

Returns the color of a specified window’s frame. See the section “Window Frame 
Colors and Patterns” in this chapter for a definition of the color table. 

Parameters 


Stack before call 

previous contents 


colorPtr 


— theWindowPtr 


Long—POINTER to five-word table to be filled with window’s color table 

Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 
previous contents 


SP 


Errors 

C 


None 


extern pascal void GetFrameColor(colorPtr,theWindowPtr) 
WindColorPtr colorPtr; 

GrafPortPtr theWindowPtr; 
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$4A0E GetInfoDraw 

Returns the pointer to the routine that draws the information bar for a specified 
window. If the window has an information bar routine, the standard window 
definition procedure calls that routine whenever the window’s frame needs to be 
drawn. See the section “Draw Information Bar Routine” in this chapter for more 
information about that routine. 

Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 
previous contents 

infoDrawPtr — Long—POINTER to routine to draw infomation bar 

SP 

Errors None 

C extern pascal VoidProcPtr GetInfoDraw(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$350E GetInfoRefCon 

Returns the value of a specified window’s wlnfoRefCon field (the value associated with 
the draw information bar routine). The field is reserved for application use. 

Parameters 

Stack before call 

Long—Space for result 

Long—POINTER to window’s GrafPort 
<— SP 


previous contents 


longspace 


— theWindowPtr — 


Stack after call 
previous contents 
infoRefCon 


Long—^Value passed to draw information bar routine 
<—SP 


Errors None 


C 


extern pascal LongWord GetInfoRefCon(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$420E 


GetMaxGrow 

Returns the maximum values to which a specified window’s content region can grow. 


Parameters 


Stack before call 

previous contents 
longspace 


— theWindowPtr — 


Long—Space for result 

Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 


previous contents 


maxGrow 


Long—Low word = maxHeight; high word = maxWidth 
<—SP 


Errors None 


C 


extern pascal LongWord GetMaxGrow(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$2A0E GetNextWindow 

Returns a pointer to the next window in the window list after a specified window; 
returns NIL if the spedlied window is the last window in the window list 

Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
SP 


Stack after call 
previous contents 


— nextWindowPtr — Long—POINTER to next window’s GrafPort in list; NIL if last window 

<—SP 


Errors None 


C 


extern pascal GrafPortPtr GetNextWindow(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$460E GetPage 

Returns the number of pbcels by which TaskMaster will scroll the content region when 
the user selects the page regions on window frame saoll bars. 

Parameters 

Stack before call 

Long—Space for result 

Long—POINTER to window’s GraflPort 
<—SP 


previous contents 


longspace 


— theWindotuPtr 


Stack after call 
previous contents 

— pageAmount — Long—^Low word = vertical amount; high word = horizontal amount 

<—SP 

Errors None 


C 


extern pascal LongWord GetPage(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$4F0E GetRectInfo 

Sets the information rectangle to the coordinates of the information bar rectangle. If 
there is no information bar in the specified window, the coordinates of the RECT data 
structure pointed to by infoR&^tPtr-sniW all be 0. The coordinate system will be local 
to the window’s frame; that is, 0,0 will be the upper left corner of the window. TTie 
coordinates can be used to set the position of objects that will be drawn in the 
information bar. 


Parameters 

Stack before call 

Long—POINTER to destination RECT where rectangle will be stored 

Long—POINTER to window’s GrafPort 
SP 


previous contents 
infoRectPtr 


— theWindowPtr 


Stack after call 


previous contents 


4— SP 


Errors None 

C extern pascal void GetRectInfo(InfoRectPtr,theWindowPtr) 

Rect *infoRectPtr; 

GrafPortPtr theWindowPtr; 
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$440E GetScroll 

Returns the number of pixels by which TaskMaster will scroll the content region when 
the user selects the arrows on window frame scroll bars. 

Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 

previous contents 

— scrollAmount — Long—^Low word * vertical amount; high word = horizontal amount 

<—SP 


Errors None 


C 


extern pascal LongWord GetScroll(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$2E0E GetStructRgn 

Returns a handle to a specified window’s structure region. See the section “Window 
Regions” in this chapter for a definition of the structure region. 

Parameters 


Stack before call 
previous contents 
longspace 


Long—Space for result 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
4-SP 


Stack after call 
previous contents 


— wStructHandle — Long—HANDLE to window’s structure region 

<—SP 


Errors None 


C 


extern pascal RgnHandle GetStruotRgn(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$4C0E 


GetSysWFlag 

Indicates whether a specified window is a system window or an application window. 


Parameters 


Stack before call 

previous contents 
wordspace 

— theWindowPtr 


Word—Space for result 
Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 
previous contents 


sysFlag 


Errors 

C 


Word—^BOOLEAN; TRUE if system window, FALSE if application window 
<—SP 


None 

extern pascal Boolean GetSysWFlag(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$300E GetUpdateRgn 

Returns a handle to a specified window’s update region. See the section 
“BeginUpdate” in this ^apter for an explanation of how the update region is used. 

Parameters 


Stack before call 
previous contents 
longspace 


Long—Space for result 


~ theWindowPtr 


Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 
previous contents 
— wVpdateHandle — 


Long—HANDLE to window’s update region 
<—SP 


Errors None 


C 


extern pascal RgnHandle GetUpdateRgn(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$330E GetWControls 

Returns the handle to the first control in the window’s control list The window’s 
control list is the list of controls aeated by the application with calls to NewControl in 
the Control Manager. 

Parameters 


Stack before call 
previous contents 


longspace 


— theWindowPtr 


Long—Space for result 

Long—POINTER to window’s GrafPort 
<— SP 


Stack after call 
previous contents 

— controlHandle — Long—HANDLE to first control in window’s control list; NIL if none 

<—SP 

Errors None 

C extern pascal CtlRecHndl GetWControls(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$2COE GetWFrame 

Returns the bit flag that describes a specified window’s frame type. See the discussion 
of the wFrame field in the section “NewWindow” in this chapter for the definition of 
the bits in the flag. 

Parameters 

Stack before call 

previous contents 
wordspace 

— theWindowPtr 


Word—Space for result 

Long—POINTER to window’s GrafPort 

4-SP 


Stack after call 

previous contents 
wFrame 


Word—Bit flag with window’s frame type 
<—SP 


Errors None 


C 


extern pascal Word GetWFrame(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$2B0E GetWKind 

Indicates whether a specified window is a system window or an application window. 

Parameters 

Stack before call 

previous contents 
wordspace 

— theWindowPtr 


Word—Space for result 
Long—POINTER to window’s GrafPort 
<— SP 


Stack after call 
previous contents 

windowKind Word—Bit 15 is 0 for application window, 1 for system window 

<— SP 

Errors None 

C extern pascal Word GetWKind(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$200E GetWMgrPort 

Returns a pointer to the Window Manager’s port. 

Parameters 

Stack before call 
previous contents 

longspace — Long—Space for result 

SP 


Stack after call 
previous contents 

wPortPtr — Long—POINTER to Window Manager’s GrafPort 

<—SP 

Errors None 

C extern pascal GrafPortPtr GetWMgrPort() 
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$290E GetWRefCon 

Returns a value from a specified window’s record that was passed to either NewWindow 
or SetWRefCon by the application. The wRefCon field is reserved for use by the 
application. 


Parameters 

Stack before call 

Long—Space for result 

Long—POINTER to window’s GrafPort 
<— SP 


previous contents 


longspace 


— theWindowPtr 


Stack after call 
previous contents 
wRefCon 


Long—Current value of wRefCon field 
<— SP 


Errors None 


C 


extern pascal LongWord GetWRefCon<theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$OEOE GetWTitle 

Returns the pointer to a specified window’s title. The string pointed to by titlePtris a 
Pascal-type string. 

Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 


— theWindowPtr — 


Long—POINTER to window’s GrafPort 
<— SP 


Stack after call 
previous contents 
titlePtr 


Long—POINTER to window’s title string 
<— SP 


Errors None 

C extern pascal Pointer GetWTitle(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$370E 


GetZoomRect 

Returns a pointer to the rectangle to be used as the content’s zoomed or unzoomed 
size for a specified window. If the zoom flag is set in the frame flag (see the section 
“GetWFrame” in this chapter), then wZoomSizePtr points to a RECT data structure 
that contains the window’s last size and position. (Dtherwise, wZoomSizePtr points to 
a RECT data structure that contains the size and position of the window’s content 
region (port) the next time the window is zoomed by a call to ZoomWindow. 


Parameters 

Stack before call 

Long—Space for result 

Long—POINTER to window’s GrafPort 
SP 


previous contents 


longspace 


— theWindowPtr 


Stack after call 

previous contents 

— WZoomSizePtr — Long —^pointer to RECT data structure used as content’s zoomed size 

^SP 

Errors None 

C extern pascal Rect * GetZoomRect(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$ 1BOE GrowWindow 

Pulls around a grow image of a specified window, following the movements of the 
mouse until the mouse button is released. The grow Image for a document window is 
a dotted outline of the entire window plus the lines delimiting the title bar, stee box, 
and scroll bar areas. See Figure 25-18. 

When there’s a mouse-down event in the size box region of the specified window, the 
application should call GrowWindow with startY and startX equal to the point where 
the mouse button was pressed (in global coordinates, as stored in the where field of 
the event record). 


Parameters 


Stack before call 


previous contents 


longspace 


minWidth 


minHeight 


StartX 


StartY 


theWindowPtr 


Long—Space for result 

Word—^Minimum width of content region 
Word—Minimum height of content region 
Word—Starting X coordinate of cursor, in global 
Word—Starting Y coordinate of cursor, in global 

Long—POINTER to window’s GrafPort 

<—SP 


coordinates 

coordinates 


Stack after call 


previous contents 


newSize 


Long—^High word = new width; low word = new height 
<—SP 


Errors None 
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C extern pascal LongWord GrowWindow(minWidth,minHeight,startX,startY, 

theWindowPtr) 

Word minWidth; 

Word minHeight; 

Integer startX; 

Integer startY; 

GrafPortPtr theWindowPtr; 

You can also use the following alternate form of the call: 

extern pascal LongWord GrowWindow(minWidth,minHeight,start,theWindowPtr) 
Word minWidth; 

Word minHeight; 

Point start; 

GrafPortPtr theWindowPtr; 


Grow image 

Figure 25-18 illustrates the grow image for a document window that contains both 
scroll bars. In general, the grow image is defined in the window definition function 
to appropriately show that the window’s size will change. 
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Width returned in high-order word 


Figure 25*18 

Grow Image of a window 


Height returned in 
low-order word 
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Your application should subsequently call the SizeWindow routine to change the port 
rectangle of the window’s GrafPort to the new one outlined by the grow image. The 
sizeRect parameter specifies limits, in pixels, on the height (vertical measurement) 
and width (horizontal measurement) of what will be the new port rectangle. The top 
coordinate of sizeRect is the minimum vertical measurement, the left coordinate is 
the minimum horizontal measurement, the bottom coordinate is the maximum 
vertical measurement, and the right coordinate is the maximum horizontal 
measurement. 

GrowWindow returns the actual size for the new port rectangle as outlined by the grow 
image when the mouse button is released. The high-order word of the long is the 
horizontal measurement in pixels; the low-order word is the vertical measurement. 

A return value of 0 indicates that the size is the same as that of the current port 
rectangle. 
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$120E HideWindow 

Makes a specified window invisible. If the window is the frontmost window and there’s 
a window behind it, HideWindow also unhighlights the window, brings the window 
behind it to the front, highlights that window, and generates appropriate activate 
events. If the specified window is already invisible, HideWindow has no effect. 


Parameters 

Stack before call 

previous contents 

— theWindowPtr — Long—POINTER to window’s GrafPort 

<—SP 


Stack after call 


previous contents 


<-SP 


Errors None 

C extern pascal void HideWindow(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$220E HiliteWindow 

Highlights or unhighlights a specified window, depending on the value of a specified 
parameter. If JHiliteFlag is TRUE, this routine highlights the window. If JHiliteBag is 
FALSE, HiliteWindow unhighlights the window. The exact way a window is highlighted 
and unhighlighted depends on its window definition procedure. 

Normally you won’t have to call this routine because you should call SelectWindow to 
make a window active and SelectWindow takes care of the necessary highlighting 
changes. To conform with the Apple Human Interface Guidelines, don’t highlight a 
window that isn’t the active window. 


Parameters 


Stack before call 
previous contents 

JHiliteFlag Word—^BOOLEAN; TRUE to highlight window, FALSE to unhighlight 

— theWindowPtr — Long —pointer to window’s GrafPort 


<—SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void HiliteWindow(fHiliteFlag,theWindowPtr) 

Boolean fHiliteFlag; 

GrafPortPtr theWindowPtr; 


Window Manager routines 


25-79 













$3A0E InvalRect 

Accumulates a specified rectangle into the update region of the window whose 
GrafPort is the current port. This tells the Window Manager that the rectangle has 
changed and must be updated. The rectangle is given in local coordinates and is then 
clipped by the Window Manager to the window’s content region. 


Important 

This routine changes the coordinates you give it. Save the coordinates if you 
need to restore them iater. 


Parameters 

Stack before call 
previous contents 

badRectPtr — Long—POINTER to RECT data structure of rectangle to be added 

<—SP 


Stack after call 


previous contents 


^SP 


Errors None 

C extern pascal void InvalRect(badRectPtr) 

Rect *badRectPtr; 
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$3B0E InvaIRgn 

Accumulates a specified region into the update region of the window whose GraflPort is 
the current port. This tells the Window Maruger that the region has changed and 
must be updated. The region is given in local coordinates and is then clipped by the 
Window Manager to the window’s content region. 


Important 

This routine changes the coordinates you give it. Save the coordinates if you 
need to restore them iater. 


Parameters 


Stack before call 

previous contents 


— badRgnHandle — Long —^handle to region to be added to update region 

SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void InvaIRgn(badRgnHandle) 

RgnHandle badRgnHandle; 
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$190E MoveWindow 

Moves a specified window to another part of the screen without affecting the window’s 
size. The upper left corner of the window’s port rectangle is moved to the screen 
point newY, newX. The local coordinates of the window’s top left corner remain the 
same. 


Parameters 


Stack before call 


previous contents 


newX 


newY 


- theWindowPtr 


Word—New X coordinate of content region’s upper left 
Word—New Y coordinate of content region’s upper left 

Long—POINTER to window’s GrafPort 

<-SP 


corner (global) 
corner (global) 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void MoveWindow(newX,newY,theWindowPtr) 

Integer newX; 

Integer newY; 

GrafPortPtr theWindowPtr; 

You can also use the following alternate form of the call: 
extern pascal void MoveWindow(newPoint,theWindowPtr) 
Point newPoint; 

GrafPortPtr theWindowPtr; 
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$090E NewWindow 

Creates a specified window as specified by its parameters, adds it to the window list, 
and returns a pointer to the new window’s GrafPort. NewWindow allocates space for 
the structure and content regions of the window and asks the window definition 
function to calculate those regions. 


Important 

NewWindow does not set the current port, but many routines require that a 
current port exist. Use the QuickDraw ii routine SetPort to set the current port. 


Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 


— paramListPtr 


Long—POINTER to parameter list (see Table 25-9) 
«-SP 


Stack after caU 
previous contents 

theWindow — Long —pointer to window’s GrafPort; NIL if error 

<— SP 


Errors 


C 


$0E01 paramLenErr First word of parameter list is the wrong size 

$0£02 allocateErr Unable to allocate memory for window record 

extern pascal GrafPortPtr NewWindow(paramListPtr) 

ParamListPtr paramListPtr; 

(continued) 
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NewWindow parameter list 

The NewWindow parameter list is shown, and each parameter is briefly described, in 
Table 25-9. 

Table 25-9 

NewWindow parameter list 


Parameter 

Length 

Description 

paramLength 

Word 

Total number of bytes in parameter table, including the paramLength 
parameter itself 

WFrameBits 

Word 

Bit flag that describes window frame type 

wTitle 

Long 

Pointer to window’s title 

wRefCon 

Long 

Reserved for application use 

wZoom 

4 words 

RECT specifying size and position of content when zoomed 

wColor 

Long 

Pointer to window’s color table 

wYOrigin 

Word 

Vertical offset of content region from data area 

wXOrigin 

Word 

Horizontal offset of content region from data area 

wDataH 

Word 

Height of entire document 

wDataW 

Word 

Width of entire document 

wMaxH 

Word 

Maximum height of content allowed by GrowWindow 

wMaxW 

Word 

Maximum width of content allowed by GrowWindow 

wScrollVer 

Word 

Number of pixels to scroll content vertically when user clicks arrow 

wScrollHor 

Word 

Number of pixels to scroll content horizontally when user clicks arrow 

wPageVer 

Word 

Number of pixels to scroll content vertically for page 

wPageHor 

Word 

Number of pixels to scroll content horizontally for page 

wInfoRefCon 

Long 

Value passed to draw information bar routine 

wInfoHeight 

Word 

Height of information bar 

wFrameDefProc 

Long 

Pointer to window definition procedure; NIL for standard 

wInfoDefProc 

Long 

Pointer to routine that draws the interior of the information bar 

wContDefProc 

Long 

Pointer to routine that draws the interior of the content region 

wPosition 

4 words 

RECT specifying window’s starting position and size 

wPlane 

Long 

Window’s starting plane 

wStorage 

Long 

Pointer to memory to use for window record 


Each of these parameters is described in more detail in the following paragraphs. 

paramLength: Total number of bytes in parameter table, including the 
paramLength parameter itself. Use labels in code to calculate the values, which are 
used mainly for error checking. Most errors with NewWindow occur because of 
typing errors occurring when the parameter list is being created. The problem can 
be compounded if the assembler or compiler skips fields because of the typing errors 
but does not generate an error. 

wFrameBits: Window frame type, as shown in Figure 25-19 (each bit flag is 
described in more detail after the illustration). 
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15 

J4 

ii 

12 

0 

10 

0 

0 

0 

0 

0 

0 

0 

0 

0 

0 


Titlebar* 1 
No title bar = 0 


fClose-^ 
Close box = 1 
No close box = 0 


fAlert 

Alert-type frame (no size and close boxes, 
no info, title, or scroll bars) = 1 
No alert-type frame = 0 


r 


At the time of publication, 
these fields should 

be 111 or000; - 

see text describing 
fGrow. 


fRScrofI 

Vertical scroll bar = 1 
No vertical scroll bar = 0 

fBScroll 

Horizontal scroll bar = 1 
No horizontal scroll bar = 0 

fGrow 


V. 


size box = 1 
No size box = 0 


fFlex 

GrowWIndow and ZoomWindow don't change origin = 1 

Origin changes = 0 


fZoom 

Zoom box on title bar = 1 
No zoom box = 0 


fMove 

Title bar is a drag region = 1 
No drag region = 0 


fQContent 

Activate window and return wlnContent^ 1 
Activate window and don't return wInContent- 0 


fVis 

Currently visible = 1 
Window is invisible = 0 


finfo -* 
Information bar = 1 
No Information bar = 0 


fCtITie 

Control's state is independent of window's state = 1 
Control's state is the same as window's state = 0 

fAllocated 

Record was allocated = 1 
Record was provided by application = 0 

fZoorDed 

Currently zoomed = 1 
Not zoomed = 0 


fHillted 

Frame Is highlighted = 1 
Frame Is not highlighted = 0 


Figure 25-19 

NewWindow window frame typ© 
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JTitle: If this bit is set to 1, the window has a title bar as part of the window frame. 

/Close: If this bit is set to 1, the window has a close box as part of the title bar. The 
window must have a title bar to have a dose box. 

/Alert: If this flag is set to 1, it indicates to the Dialog Manager that it should draw an 
alert window. The /In/o, /Zoom, /Flex, /Grow, /BScroll, /RScroll, /Close, and /Title 
flags should all be set to 0. 

/RScroU: If this bit is set to 1, the window has a right (vertical) scroll bar as part of the 
window frame. 

/BScroll: If this bit is set to 1, the window has a bottom (horizontal) scroll bar as part of 
the window frame. 

/Grow: If this bit is set to 1, the window has a size box as part of the window frame. 

❖ Note: If /Grow is set to 1, /BScroll and /RScroll must also be set to 1; to have a 
window frame size box, you must have at least one window frame saoll bar. The 
fields should be either 111 or 000. 

/Flex: If this bit is set to 1, the data height and width are flexible, which means that 
GrowWindow and ZoomWindow will not change the window's origin as needed. 

/Zoom: If this bit is set to 1, the window has a zoom box as part of the title bar. The 
window must have a title bar to have a zoom box. 

/Move: If this bit is cleared to 0, the window's title bar is not considered a drag region 
and therefore the window cannot be moved, 

/QContent: If this bit is set to 1 and there is a button-down event inside an inactive 
window’s content, the window will be selected and a wInContent message will be 
returned by TaskMaster. This feature is useful if you would like to act on any button 
down in the content, even if it was also used to activate the window. 

/Vis: If this bit is set to 1, the window is visible. 

/In/o: If this bit is set to 1, wIn/oHeight and wIn/oDe/Proc should be given values. 

/CtrlTie: When the window is inactive (unhighlighted), its controls are also considered 
inactive without regard for the active state of the control Whenever an activate event 
is received for the window, you should redraw all of the controls for the window to 
make sure the controls appear in their proper states. 

/Allocated: If this flag is set when Close Window is called, the window record will be 
freed. Normally you never have to set or read this flag. 

/Zoomed: This flag is not used if /Zoom is 0. 

/Hilited: This flag will be set by NewWindow, so whatever value you provide will be 
ignored. 
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wTitle: Pointer to window’s title. If the window has no title bar, this value can be 0. 

The first byte in the string should be the length of the string followed by the ASCII 
characters of the title. The title string should always include a space as the first and last 
character of the string. 

wRefCon: Application-defined reference value. This value is reserved for 
application use and can be any value. 

wZootn: RECT data structure specifying size and position of the content region when 
the window is zoomed. If the bottom side of the rectangle is 0, a default RECT will be 
used. The default is set so the window uses the entire screen. 

wColor: Pointer to window’s color table. This is the color table used to draw the 
window’s frame. NIL uses the default color table. 

wYOrigin: Vertical offset of content region from data area. This value is the vertical 
value passed to SetOrigin when TaskMaster is used to draw inside the content region. It 
is also used to compute the right (or vertical) scroll bar. Set wYOrigin to 0 if you are 
not using window frame scroll bars. 

wXOrigin: Horizontal offset of content region from data area. This value is the 
horizontal value passed to SetOrgin when TaskMaster is used to draw inside the content 
region. It is also used to compute the bottom (or horizontal) scroll bar. Set wXOrigin 
to 0 if you are not using window frame scroll bars. 

wDataH: Height of entire data area. Used to compute the right scroll bar. Set it to 0 
if you are not using window frame scroll bars. 

wDataW: Width of entire data area. Used to compute the bottom scroll bar. Set it to 
0 if you are not using window frame scroll bars. 

wMaxH: Maximum content height allowed when growing the window. This value is 
passed to GrowWindow when called by TaskMaster. If set to 0, a default value will be 
used so the window will take up the height of the desktop. Set wMaxHio 0 if your 
window frame does not have a size box. 

wMaxW: Maximum content width allowed when growing the window. This value is 
passed to GrowWindow when called by TaskMaster. If set to 0, a default value will be 
used so the window will take up the width of the desktop. Set wMaxWXo 0 if your 
window frame does not have a size box. 

wScroUVer: Number of pixels to scroll the content region when the up or down 
arrows are selected in the right scroll bar. Used only if the scroll bar is part of the 
frame and TaskMaster is used. Set wScroUVerto 0 if you are not using window frame 
scroll bars. 

wScroUHor: Number of pixels to scroll the content region when the left or right 
arrows are selected in the bottom scroll bar. Used only if the scroll bar is part of the 
frame and TaskMaster is used. Set wScrollHorXo 0 if you are not using window frame 
scroll bars. 

(continued) 
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wPageVer: Number of pixek to scroll the content region when the up or down page 
regions are selected in the right scroll bar. Used only if the scroll bar is part of the 
frame and TaskMaster is used. Set wPageVerto 0 for the default value of the content 
region's current height minus 10. 

wPageHor: Number of pixels to scroll the content region when the left or right page 
regions are selected in the bottom scroll bar. Used only if the scroll bar is part of the 
frame and TaskMaster is used. Set wPageHor to 0 for the default value of the content 
region's current width minus 10. 

wlnfoRefCon: Value passed to draw information bar routine. The value can be 
anything the application would like, such as a pointer to a string to be printed in the 
information bar. Set wInfoRefCon to 0 if you are not using an information bar. 

wlnfoHeight: Height of the information bar if /Info (bit 4) of wFrame is set to 1. 

wFrameDefProc: Pointer to window's definition procedure; NIL for a standard 
document window. 

wIttfoDefProc: Pointer to routine that will be called to draw in the information bar. 
Set it to 0 if you are not using window frame information bar. 

wContDefProa Pointer to routine that will be called to draw the window's content 
region. If you are using window frame scroll bars, this value must be set. 

If you are not using window frame saoll bars and want to handle update events 
yourself, set this value to NIL 

If you are not using window frame scroll bars, but you would like TaskMaster to handle 
update events, set this value. Hie routine will be called when the content region needs 
to be drawn. On entry, the current port will be the window's GrafPort, the visible 
region will be set to the update area, and the origin set There are no input or output 
parameters. Exit the routine via RTL. 

wPosItion: A RECT data structure specifying the window's starting position and size 
in global coordinates. The RECT becomes the port rectangle of the window's 
GrafPort; note, however, that the port rectangle is in local coordinates. NewWindow 
sets the top left corner of the port rectangle to (0,0). For the standard types of 
windows, this RECT data structure defines the content region of the window. 

wPlane: Pointer to window's starting plane; that is, to the window's GrafPort behind 
which this window should appear—0 for bottommost, $FFFFFFFF for topmost. 

wStorage: Pointer to memory to use for window's record. If set to NIL, memory for 
the record will be allocated by the Window Manager. Because window records are not 
completely defined, the size needed for one is unknown and you must allow at least 325 
bytes for a window record. It is usually best to have the record allocated by the 
Window Manager. The ability to use your own memory for a window record is 
provided in case you need to put up a window informing the user that there is no more 
memory. 
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$210E PinRect 

Pins a specified point inside a specified rectangle. If the point is inside the rectangle, 
the point is returned; otherwise, the point associated with the nearest pixel within the 
rectangle is returned. (The high-order word of the pinned point is the X coordinate; 
the low-order word is the Y coordinate.) 

More precisely, for a specified rectangle (.left, top,right, bottom) and a specified 
point (h,v), PinRect does the following: 

■ If A < left, it returns left. 

■ If t; < top, it returns top. 

■ If A > right, it returns right -1. 

■ If y > bottom, it returns bottom -1. 

❖ Note: The 1 is subtracted when the specified point is below or to the right of the 
specified rectangle so that a pbcel drawn at that point will lie within theRect. 

Parameters 

Stack before call 

previous contents 

— longspace 

theXPt 
theYPt 

tbeRectPtr 


Long—Space for result 

nil 

Word—coordinate of point to be pinned 
Word —Y coordinate of point to be pinned 

Long—POINTER to RECT data structure defining boundary of point 
SP 


Stack after call 


previous contents 


pinnedPt 


Long—POINT; high word = X coordinate, low word = Y coordinate 


<—SP 
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Errors 


None 


C extern pascal Long PinRect(theXPt,theYPt,theRectPtr) 

Integer theXPt; 

Integer theYPt; 

RectPointer theRectPtr; 

You can also use the following alternate form of the call: 

extern pascal Long PinRect(thePoint,theRectPtr) 

Point thePoint; 

RectPointer theRectPtr; 

❖ Note: C Pascal-type functions do not deal properly with data structures returned 
on the stack. The Long result returned by this call can be passed to any calls 
requiring a point as a parameter. You cannot use the C dot operator to access the 
individual Y and X coordinates within the value returned by this call. 
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$390E RefreshDesktop 

Redraws the entire desktop and all the windows. This routine can be useful when the 
entire screen is clobbered by some application-specific, non-Window Manager 
operation. 


Parameters 

Stack before call 
previous contents 

redrawRect — Long—POINTER to RECT of rectangle to redraw; NIL for entire screen 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void RefreshDesktop(redrawRect) 

Rect *redrawRect; 
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$110E SelectWindow 

Makes a specified window the active window. Ihis routine unhighlights the previously 
active window, brings the specified window in front of all other windows, highlights it, 
and generates appropriate activate events. Call this routine if you are not using 
TaskMaster and there's a mouse-down event in the content region of an inactive 
window. 


Parameters 

Stack before call 

previous contents 

— theWindowPtr — Long— POINTER to window's GrafPort 

<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 


C 


extern pascal void SelectWindow(theWindowPtr) 
GrafPortPtr theWindowPtr; 
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$140E SendBehind 

Changes the position of a specified window, redrawing any exposed windows. 

If behindWindowPtr is -2 ($FFFFFFFE), it sends the specified window behind all other 
windows. If behindWindowPtr is -1 C$FFFFFFFF), it puts the specified window in front 
of all other windows. If the specified window is the active window, the routine 
unhighlights the active window, highlights the new active window, and generates the 
appropriate activate events. 


Parameters 


Stack before call 
previous contents 


—behindWindowPtr — 


Long— POINTER to GrafPort or $FFFFFFFF = top or $FFFFFFFE = bottom 


— theWindowPtr 


Long— POINTER to window’s GrafPort 
<r- SP 


Stack after call 


previous contents 


<— SP 


Errors None 


C 


extern pascal 

GrafPortPtr 

GrafPortPtr 


void SendBehind(behindWindowPtr,theWindowPtr) 
behindWindowPtr; 
theWindowPtr; 
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$490E SetContentDraw 

Sets the pointer to the routine to draw the content region of a specified window. 

TaskMaster calls this routine when it gets an update event for that window. See the 
section “Draw Content Routine” in this chapter for more infomation about the draw 
routine. 


Parameters 


Stack before call 
previous contents 


— contentProcPtr — 


Long—POINTER to routine to draw content region 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
«-SP 


Stack after call 


previous contents 


<—SP 


Errors None 


C 


extern pascal 
VoidProcPtr 
GrafPortPtr 


void SetContentDraw(contentDrawPtr,theWindowPtr) 
contentDrawPtr; 
theWindowPtr; 
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$3F0E SetContentOrigin 

Sets the origin of the window’s GraflPort when handling an update event. The values 
are used by TaskMaster to set the origin of the window’s GrafPort and are also used by 
the Window Manager to compute scroll bars in the window frame. See the section 
“Origin Movement” in this chapter for an illustration of the origin values. 

Setting the origin values generates an update event. 


Parameters 


Stack before call 


previous contents 


xOrigin 


yOrigin 


— theWindowPtr 


Word—Content 
Word—Content 

Long—POINTER 

<—SP 


region’s horizontal offset into data area 
region’s vertical offset into data area 

to window’s GrafPort 


Stack after call 
previous contents 


4-SP 


Errors None 


C extern pascal void SetContentOrigin(xOrigin,yOrigin,theWindowPtr) 

Word xOrigin; 

Word yOrigin; 

GrafPortPtr theWindowPtr; 
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$570E SetContentOrigin2 

Sets the origin of the window’s GrafPort when handling an update event and allows the 
application to scroll or not scroll the window’s content region. If scrolWlag is set to 
1, this call is the same as SetContentOrigin. If scrollFlag is set to 0, the window’s 
origin will be set without the Window Manager scrolling the data in the window. This 
feature is useful, for example, if a window’s data area has to be expanded to the left or 
above the current origin and you don’t want your application to redraw everything in 
the window. 

The xOrigin andyOriginvzlues are used by TaskMaster to set the origin of the 
window’s GrafPort and are also used by the Window Manager to compute scroll bars 
in the window frame. See the section “Origin Movement” in this chapter for an 
illustration of the origin values. 

Setting the origin values generates an update event. 


Parameters 

Stack before call 


Word—0 to not scroll content, 1 to scroll content 
Word—Content region’s horizontal offset into data area 
Word—Content region’s vertical offset into data area 

Long—POINTER to window’s GrafPort 
<— SP 


previous contents 
scrollFlag 
xOrigin 
yOrigin 

— theWindowPtr 


Stack after call 


previous contents 


<—SP 


Errors None 


C extern pascal void SetContentOrigin2(scrollFlag,xOrigin,yOrigin, 

theWindowPtr) 

Word scrollFlag; 

Word xOrigin; 

Word yOrigin; 

GrafPortPtr theWindowPtr; 
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$410E SetDataSize 

Sets the height and width of the data area of a specified window. Setting these values 
will not change the scroll bars or generate update events. 


Parameters 


Stack before call 


previous contents 

dataWidth Word—^Width of data area in pixels 

dataHeight Word—^Height of data area in pixels 


— theWindowPtr — 


Long —POINTER to window’s GrafPort 
<— SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetDataSize(dataWidth,dataHeight,theWindowPtr) 

Word dataWidth; 

Word dataHeight; 

GrafPortPtr theWindowPtr; 
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$320E SetDefProc 

Sets the pointer to the routine that defines a window’s frame and behavior. See the 
section “Defining Your Own Windows” in this chapter for an explanation of what a 
definition procedure does. 

Parameters 


Stack before call 

previous contents 
— wDefProcPtr 


Long—POINTER to window’s definition procedure 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
SP 


Stack after call 

previous contents I 

U— SP 


Errors None 


C 


extern pascal 
LongProcPtr 
GrafPortPtr 


void SetDefProc(wDefProcPtr,theWindowPtr) 
wDefProcPtr; 
theWindowPtr; 
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$OFOE SetFrameColor 

Sets the color of a specified window’s frame. Does not redraw the window. Do a 
Hide Window call before the SetFrameColor call and a ShowWindowcall after the 
SetFrameColor call to redraw the window in its new colors. 

The interaction between the newColorPtr ioA theWindowPtr pinvaex&TS is shown in 
Figure 25-20. See the section “Window Frame Colors and Patterns” in this chapter for 
a definition of the color table. 


Parameters 


Stack before call 
previous contents 
newColorPtr — 


Long—POINTER to five-word pattern/color table; NIL for default table 


— theWindowPtr — 


Long—POINTER to window’s GrafPort; NIL for window default 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 


C 


extern pascal 

WindColorPtr 

GrafPortPtr 


void SetFrameColor(newColorPtr,theWindowPtr) 
newColorPtr; 
theWindowPtr; 


(continued) 


Window Manager routines 


25-99 











The newColorPtr and theWindowPtr parameters 

The precise results of the four possible combinations of the newColorPtr and 
theWindowPtr parameters are shown in Figure 25-20. 


^ SetFrameColor parameters ^ 

newColorPtr theWindowPtr I Result 


Pointer 


Pointer 


NIL 


NIL 


Pointer 


Changes a specified window 
to a specified color table 



Makes a specified color table 
the default table for 
all future windows 


Pointer 


Changes the specified window 
to the Window Manager's 
startup color table 


Replaces the default color table 
for all future windows with the 
Window Manager's startup 
color table 


Figure 25-20 

SetFrameColor newColorPtr and theWindowPtr values 
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$160E SetInfoDraw 

Sets the pointer to a routine that draws the information bar for a specified window. If 
the window has an information bar, the standard window definition procedure calls 
this routine whenever the window’s frame needs to be drawn. See the section “Draw 
Information Bar Routine” in this chapter for more information about the draw 
routine. 


Parameters 


Stack before call 
previous contents 
— infoDrawPtr 


— theWindowPtr 


Long—POINTER to draw information bar routine 

Long—POINTER to window’s GrafPort 
<— SP 


Stack after call 
previous contents 


Errors 

C 


<—SP 


None 

extern pascal void SetInfoDraw(infoDrawPtr,theWindowPtr) 
VoidProcPtr infoDrawPtr; 

GrafPortPtr theWindowPtr; 
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$360E SetInfoRefCon 

Sets the value associated with the draw information bar routine for a specified window. 
That value is reserved for use by the applicaton. 

Parameters 


Stack before call 
previous contents 
infoRefCon 


Long—^Value to pass to draw information bar routine 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 


previous contents- 


SP 


Errors None 


C extern pascal void SetInfoRefCon(infoRefCon,theWindowPtr) 

LongWord infoRefCon; 

GrafPortPtr theWindowPtr; 
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$430E SetMaxGrow 

Sets the maximum values to which a specified window’s content region can grow. 

Parameters 
Stack before call 

Word—^Maximum content width in pixels 
Word—^Maximum content height in pixels 

Long—POINTER to window’s GrafPort 

<—SP 


previous contents 
max Width 
maxHeight 

— theWindowPtr 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetMaxGrow(maxWidth,maxHeight,theWindowPtr) 

Word maxWidth; 

Word maxHeight; 

GrafPortPtr theWindowPtr; 
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$340E SetOriginMask 

Specifies the mask used to put the horteontal origin on a grid. 

SetOriginMask is useful when you are using a scrollable window in 640 mode with 
dithered colors. In that mode, pixels must keep the same horizontal position to 
remain the same color. Scrolling windows can change the color by putting the pixels 
in the wrong horizontal position. SetOriginMask prevents this problem by providing 
an originMask that will be ANDed by TaskMaster with any new horizontal origin to 
force the origin to certain boundaries. The default is $FFFF, single pixel. 


Parameters 

Stack before call 

Word—Mask used to place horizontal origin on a grid 
Long—POINTER to window’s GrafPort 
<—SP 


previous contents 
originMask 


— theWindowPtr 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetOriginMask(originMask,theWindowPtr) 

Word originMask; 

GrafPortPtr theWindowPtr; 
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$470E SetPage 

Sets the number of pixels by which TaskMaster will scroll the content region when the 
user selects the page regions on window frame scroll bars. 


Parameters 


Stack before call 


previous contents 


hPage 


vPage 


— theWindowPtr — 


Word—^Number of pbcels to page horizontally 
Word—Number of pixels to page vertically 

Long—POINTER to window’s GrafPort 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetPage(hPage,vPage,theWindowPtr) 

Word hPage; 

Word vPage; 

GrafPortPtr theWindowPtr; 
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$450E SetScroll 

Sets the number of pixels by which TaskMaster will scroll the content region when the 
user selects the arrows on window frame scroll bars. 


Parameters 


Stack before call 

previous contents 


hScroll 


vScroll 


theWindowPtr 


Word—Number of pixels to scroll horizontally 
Word—Number of pixels to scroll vertically 

Long—POINTER to window’s GrafPort 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetScroll(hScroll,vScroll,theWindowPtr) 

Word hScroll; 

Word vScroll; 

GrafPortPtr theWindowPtr; 
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$4B0E SetSy$Window 

Marks a specified window as a system window. 

Parameters 

Stack before call 
previous contents 

— theWindowPtr — Long —^pointer to window’s GrafPort 

<—SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SetSysWindow(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$2D0E SetWFrame 

Sets the bit flag that describes a specified window’s frame type. The window frame is 
not redrawn. See the discussion of wFrameBits in the section “NewWindow” in this 
chapter for the definition of the bits of the wFrame parameter. 

❖ Note: Normally, you won’t need to call this routine; instead, you should set up the 
window frame correctly with the NewWindow routine. The SetWFrame routine is 
provided for custom window definition procedures. 


Parameters 

Stack before call 

Word—Bit flag specifying window’s frame type 
Long—POINTER to window’s GrafPort 
<— SP 


previous contents 
wFrame 


— theWindowPtr — 


Stack after call 

previous contents I 

|<—SP 

Errors None 

C extern pascal void SetWFrame(wFrame,theWindowPtr) 

Word wFrame; 

GrafPortPtr theWindowPtr; 
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$4E0E SetWindowIcons 

Sets the icon font for the Window Manager. See the section “Window Manager Icon 
Font” in this chapter for more information about the font. 

If you want to use the call to simply retrieve the handle of the current font, specify a 
negative value for newFontHandle. 

Parameters 


Stack before call 

previous contents 
longspace 


Long—Space for result 


— newFontHandle — 


Long—^HANDLE to new icon font; negative to not replace font 
<—SP 


Stack after call 
previous contents 

~ oldFontHandle — Long—HANDLE to icon font before call 

<— SP 


Errors None 

C extern pascal FontHndl SetWindowIcons(newFontHandle) 

FontHndl newFontHandle; 
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$280E SetWRefCon 

Sets a value that is inside a specified window record and is reserved for the 
application’s use. 

Parameters 


Stack before call 
previous contents 
wRefCon 


Long—Value of wRefCon field 


— theWindowPtr 


Long—POINTER to window’s GraflPort 
SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetWRefCon(wRefCon,theWindowPtr) 

Longint wRefCon; 

GrafPortPtr theWindowPtr; 
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$ODOE SetWTitle 

Changes the title of a specified window to a specifed title and redraws the window. The 
string pointed to by tUlePtr must be a Pascal-type string. 


Warning 

The string pointed to by tltlePtr must not be changed or moved. 


Parameters 


Stack before call 

previous contents 
titlePtr 


Long—POINTER to new title 


— theWindowPtr 


Long—POINTER to window’s GrafPort 
SP 


Stack after call 


previous contents 


^SP 


Errors None 

C extern pascal void SetWTitle(titlePtr,theWindowPtr) 

Pointer titlePtr; 

GrafPortPtr theWindowPtr; 
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$3dOE SetZoomRect 

Sets the rectangle to be used as the content’s zoomed or unzoomed size for a specified 
window. If the window is currently in a zoomed state (that is, bit 2, the JZoomedhil, 
is set to 1 in the wFrame flag—^see the section “NewWindow” in this chapter), 
wZoomSizePtr ^o\Ad point to a RECT data structure that specifies the window’s 
unzoomed size and position. 

If the window is currently in an unzoomed state (that is, the Roomed bit is set to 0), 
wZoomSizePtr shoxiXd point to a RECT data structure that specifies the zoomed size 
and position of the window. The rectangle will be used as the window’s content region 
(port) the next time the window is zoomed by a call to ZoomWindow. 


Parameters 

Stack before call 

Long—POINTER to rectangle to be used as content’s zoomed size 

Long—POINTER to window’s GrafPort 
<—SP 


previous contents 


— wZoomSizePtr — 


— theWindowPtr 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void SetZoomRect(wZoomSizePtr,theWindowPtr) 

Rect *wZoomSizePtr; 

GrafPortPtr theWindowPtr; 
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$230E ShowHide 

Shows or hides a window. If shmuFlag is TRUE, ShowHide makes the specified 
window visible if it’s not already visible and has no effect if it is already visible. If 
showFlag is FALSE, ShowHide makes the window invisible if it’s not already invisible 
and has no effect if it is already invisible. 

Unlike Hide Window and ShowWindow, ShowHide never generates activate events or 
changes the highlighting or front-to-back ordering of windows. 


Important 

Us© this procedure carefully and only In special circumstances In which you 
need more control than Is allowed by ShowWindow and HIdeWindow. You 
could end up with an active window that Isn't highlighted. 


Parameters 


Stack before call 

previous contents 
showFlag 

— theWindowPtr 


Word—BOOLEAN; TRUE to show, FALSE to hide 
Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 


C extern pascal void ShowHide(showFlag,theWindowPtr) 

Boolean showFlag; 

GrafPortPtr theWindowPtr; 
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$130E ShowWindow 

Makes a specified window visible if it was invisible and then draws the window. It does 
not change the front-to-back ordering of the windows. If you have previously hidden 
the frontmost window with HideWindow, HideWindow will have brought the window 
behind it to the front If you then do a ShowWindow of the window you hid, it will no 
longer be frontmost 

If the specified window is already visible, ShowWindow has no effect. 


Parameters 

Stack before call 

previous contents 

— theWindowPtr — Long— pointer to window’s GrafPort 

<—SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void ShowWindow(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$1C0E Size Window 

Enlarges or shrinks the port rectangle of the specified window’s GrafPort to a specified 
width and height If the new width and height are specified as 0, SizeWindow does 
nothing. The window’s position on the screen does not change. When the new 
window frame is drawn, if the width of a document window changes, the title is 
recentered in the title bar, or if it no longer fits, it is truncated. 


Parameters 


Stack before call 

previous contents 


newWidth 


newHetght 


theWindowPtr 


Word —^New width of window in pixels 
Word —^New height of window in pixels 

Long —POINTER to window’s GrafPort 

SP 


Stack after call 


previous contents 


<— SP 


Errors None 

C extern pascal void SizeWindow(newWidth,newHeight,theWindowPtr) 

Word newWidth; 

Word newHeight; 

GrafPortPtr theWindowPtr; 
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$4D0E StartDrawing 

Makes a specified window the current port and sets its origin. After the call, any 
drawing occurs inside the specified window’s content area and in the proper 
coordinate system. 


Important 

Do not coll StartDrawing between a BeglnUpdate and an EndUpdate call. Also, 
when you have finished drawing, call the QuickDraw II routine SetOrigin(0,0). 


StartDrawing can be used for drawing in a window’s content region outside of update 
events. 

❖ Note: StartDrawing is useful only with standard document windows with frame 
scroll bars. Otherwise, only a SetPort call is needed to make the correct port 
current. 

Parameters 

Stack before call 

previous contents 

— theWindowPtr — Long —pointer to window’s GrafPort 

<— SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void StartDrawing(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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$500E StartInfoDrawing 

Allows an application to draw or hit test outside of its information bar definition 
procedure. If there is no information in the window, the coordinates of the RECT 
data structure pointed to by infoRectPtrWAX all be 0. The coordinate system will be 
local to the window’s frame; that is, 0,0 will be the upper left corner of the window, 
and the current GrafPort will be the Window Manager’s. 

You can set the clip region after a StartInfoDrawing call and before an 
EndInfoDrawing call; this is not tme from within the information bar definition 
procedure. 


Important 

When you finish dealing with the Information bar, you must call the 
EndInfoDrawing routine before you make any other calls to the Window 
Manager. 


Parameters 


Stack before call 
previous contents 
infoRectPtr 


Long—POINTER to RECT where information bar’s data will be stored 


~ theWindowPtr — 


Long—POINTER to window’s GrafPort 
<—SP 


Stack after call 

previous contents I 

I4- SP 

Errors None 

C extern pascal void StartInfoDrawing(infoRectPtr,theWindowPtr) 

Rect *infoRectPtr; 

GrafPortPtr theWindowPtr; 
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$1D0E TaskMaster 

Calls GetNextEvent and looks in the event part of the task record to see if it can handle 
the event. If no event is returned by GetNextEvent, 0 is returned in taskCode. For 
further description of TaskMaster’s activities, see the following section “TaskMaster 
Pseudocode." 


Parameters 


Stack before call 
previous contents 


wordspace 


taskMask 


taskRecPtr — 


Word—Space for result 

Word—Mask used by TaskMaster to call GetNextEvent 
Long—POINTER to Window Manager task record 
<— SP 


Stack after call 

previous contents 
taskCode 


Word—Code indicating action to be taken-, 0 = no further task to perform 
<—SP 


Errors $0E03 taskMaskErr Reserved bits not clear in wmTaskMask field of task 

record 

C extern pascal Word TaskMaster(taskMask,taskRecPtr) 

Word taskMask; 

WmTaskRecPtr taskRecPtr; 
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TaskMaster pseudocode 

TaskMaster can be a powerful tool, and can take care of much of the mundane 
processing of events. Because the routine is so important, this section presents 
pseudocode describing TaskMaster’s operations. 

To perform its functions, TaskMaster takes the following steps: 

Calls the Desk Manager routine SystemTask. 

Calls the Event Manager routine GetNextEvent with a TaskRec and eventMask 

The wmMessage field of TaskRec is duplicated into the wmTaskData field of 
TaskRec. 

If any of the reserved bits in the wmTaskMask field are not 0: 

{ 

Low word of wmTaskData = 0. 

Returns nullEvt ($0000). 

Error returned: wmTaskMaskErr ($0E03). 

} 

If tumWhat field, of TaskRec = nullEvt ($0000): 

{ 

Low word of TaskData = 0. 

Returns nullEvt ($0000). 

} 

If wmWhat field of TaskRec = updateEvt ($0006): 

{ 

If wmTaskMask bit tmUpdate (bit 1) = 0: 

{ 

wmTaskData = pointer to window to be updated. 

Returns updateEvt ($0006). 

} 

If window’s wContDeJProc field = 0: 

{ 

wmTaskData = pointer to window to be updated. 

Returns updateEvt ($0006). 

} 

Calls the BeginUpdate routine. 

The window’s draw routine in window’s wContDeJProc field is called 
(routine in application). 

Calls the EndUpdate routine. 

wmTaskData low word = updateEvt ($0006). 

Returns nullEvt ($0000). 

^ (continued) 
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If wmWhatiield of TaskRec = activateEvt ($0008): 

{ 

If umTaskMask bit tmCRedraw (bit 13) = 1: 

{ 

If wframehit fCtlJleQoii 3) = 1: 

{ 

Calls the Control Manager routine DrawControls to draw 
controls in proper state. 

} 

} 

wmTaskData = pointer to window that was activated or deactivated (check 
modifier field). 

Returns activateEvt ($0008). 

} 

If tomWhat field of TaskRec = keyDownEvt ($0003) OR autoKeyEvt ($0005): 

{ 

If wmTaskMask bit tmMenuKey (bit 0) = 0: 

{ 

wmTaskData = message field as returned by GetNextEvent. 

Returns keyDownEvt ($0003). 

} 

Calls the Menu Manager routine MenuKey with the given TaskRec for the 
system menu bar. 

Go to Menu Selection. 

(The remainder of TaskMaster from this point is the same as when the Menu 
Manager routine MenuSelect is called.) 

} 

If tvmWhat fiQ\d of TaskRec does not equal mouseDownEvt ($(XX)1): 

{ 

Returns what field from TaskRec. 

} 
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If tumWhat field of TaskRec = mouseDownEvt($0001): 

{ 

If TaskMask bit tmFindWQpk 2) = 0: 

{ 

wmTaskData = message field from GetNextEvent. 

Returns mouseDownEvt ($0001). 

} 

Calls FindWindow. 

If FindWindow returns wInMenuBar ($0011): 

{ 

If TaskMask tmMenuSel (bit 3) = 0: 

{ 

Low word of wmTaskData = 0. 

Returns wInMenuBar ($0011). 

} 

MenuSelect is called with TaskRec passed to TaskMaster. 

Menu Selection: 

If low word of umTaskData = 0, then no selection made: 

{ 

If wmTaskMask bit tmlnactive (bit 14) = 0: 

{ 

Low word of wmTaskData = wInMenuBar ($0011). 
Returns nullEvt ($0000). 

} 

If high word of wmTaskData = nonzero: 

{ 

Low word of umTaskData = 0. 

High word of wmTaskData = ID of selected inactive 
menu item. 

Returns winactMenu ($001C). 

} 

Low word of wmTaskData = wInMenuBar ($0011). 

Returns nullEvt ($0000). 

} 

(continued) 
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Else, menu selection made: 

{ 

If low word of wmTaskData (menu item ID) < 250: 

{ 

If wmTaskMask bit tmOpenNDA (bit 4) = 0: 

{ 

Low word of wmTaskData = ID of seleaed 
menu item. 

High word of wmTaskData = ID of menu 
from which selection was made. 

Returns wlnDeskltem ($001A). 

} 

Calls the Desk Manager routine OpenNDA to open 
the desk accessoryr selected. 

Calls Menu Manager routine HiliteMenu to 
unhighlight the selected menu. 

Low word of wmTaskData = wlnDeskltem 
($001A). 

Returns nullEvt ($0000). 

} 

If TaskMask bit tmSpecial (bit 12) = 0: 

{ 

Low word of wmTaskData = ID of seleaed menu 
item. 

High word of wmTaskData = ID of menu from 
which selection was made. 

Returns wInSpecial ($0019). 

} 

If top window is an application (nonsystem) window: 

{ 

Low word of wmTaskData = ID of seleaed menu 
item. 

High word of wmTaskData = ID of menu from 
which selection was made. 

Returns wInSpecial ($0019). 

} 

If low word of wmTaskData (menu item ID) = 255 (Qose 
item): 

{ 

Calls Desk Manager routine CloseNDAbyWinPtr 
for top window (system window). 

Calls HiliteMenu to unhighlight the selected menu. 
Low word of wmTaskData = wClosedNDA ($001D). 
Returns nullEvt ($0000). 

} 
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If low word of umiTaskData (menu item ID) = 250, 251, 252, 
253, or 254 (edit item): 

{ 

Calls Desk Manager routine SystemEdit with ID of 
special edit menu item. 

If SystemEdit returns FALSE: 

{ 

Low word of wmTaskData = ID of selected 
menu item. 

High word of wmTaskData = ID of menu 
from which selection was made. 

Returns winSpecial ($0019). 

} 

(Top system window handled the special menu item 
selection.) 

Calls the Menu Manager routine HiliteMenu to 
unhighlight the selected menu. 

Low word of TaskData = wCalledSysEdit 
($001E). 

Returns nullEvt ($0000). 

} 

(Low word of wmTaskData (menu item ID) > 255.) 

Low word of wmTaskData = ID of selected menu item. 

High word of wmTaskData = ID of menu from which 
selection was made. 

Returns wInMenuBar ($0011). 

} (end menu selection) 

} (end FindWindow wInMenuBar) 

If FindWindow returns a negative value: 

{ 

If wmTaskMask bit tmSysClick (bit 5) = 0: 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns result from FindWindow. 

} 

Calls Desk Manager routine SystemClick with result from 
FindWindow. 

wmTaskData low word = wClickCalled ($0012). 

Returns nullEvt ($0000). 


(continued) 
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If FindWindow returns wInDrag ($0014); 

{ 

If wmTaskMask bit tmDragW (bit 6) = 0: 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns winDrag ($0014). 

} 

If bit 8 in the modifier field of TaskRec (Apple key up) and the 
window is not active: 

{ 

Calls SelectWindow to make window active. 

} 

Calls DragWindow. 
wmTaskData = winDrag ($0014). 

Returns nullEvt ($0000). 

} 

If FindWindow returns wInContent ($0013): 

{ 

If wmTaskMask bit tmContent (bit 7) = 0: 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns wInContent ($0013). 

} 

If the window is not active: 

{ 

Calls SelectWindow to make window active. 

} 

If wFrame field JQContent (bit 6) ■= 1: 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns wInContent ($0013). 

} 

Low word of wmTaskData = wInContent ($0013). 

Returns nullEvt ($0000). 

} 
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If FindWindow returns wInGoAway ($00l6): 

{ 

If wmTaskMask bit tmClose (bit 8) = 0: 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns wInGoAway ($00l6). 

} 

Calls TrackGoAway. 

If TrackGoAway returns TRUE; 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns wInGoAway ($00l6). 

} 

Low word of wmTaskData - wInGoAway ($0016). 

Returns nullEvt ($0000). 

} 

If FindWindow returns wInZoom ($0017): 

{ 

If wmTaskMask bit tmZoom (bit 9) = 0: 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns wInZoom ($0017). 

} 

Calls TrackZoom. 

If TrackZoom returns TRUE: 

{ 

Calls ZoomWindow. 

Low word of wmTaskData = winZoom ($0017). 

Returns nullEvt ($0000). 

) 

Low word of wmTaskData = wTrackZoom ($00110. 

Returns nullEvt ($0000). 

} 

If FindWindow returns winGrow ($0015): 

{ 

If wmTaskMask bit tmGrow (bit 10) = 0: 

{ 

wmTaskData = window pointer returned from FindWindow. 
Returns wInGrow ($0015). 

} 

Calls GrowWindow. 

Calls SizeWindow with results from GrowWindow. 

Low word of wmTaskData = winGrow ($0015). 

Returns nullEvt ($0000). 

} 


(continued) 
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If FindWindow returns wininfo ($0018): 

{ 

If wmTaskMask bit tminfo (bit 15) = 1: 

{ 

If window is not active: 

{ 

Calls SelectWindow. 

Low word of wmTaskData = wInInfo ($0018). 
Returns nullEvt ($0000). 

) 

} 

wmTaskData = window pointer returned from FindWindow. 

Returns wininfo ($0018). 

} 

If FindWindow returns wInFrame ($(X)1B): 

{ 

If wmTaskMask hit tmScroll (bit 11) = 0: 

{ 

umTaskData = window pointer returned from FindWindow. 
Returns wInFrame ($001B). 

} 

If window is not active: 

{ 

Calls SelectWindow to make active. 

Low word of wmTaskData = wHitFrame ($0020). 

Returns nullEvt ($0000). 

} 

If button was on a window frame control: 

{ 

Low word of wmTaskData = wHitFrame ($0020). 

Returns nullEvt ($(XX)0). 

} 

Calls TrackControl with an action procedure within TaskMaster. 

The action procedure in TrackMaster performs scrolling and 
updates. 

Low word of umTaskData = winFrame ($001B). 

Returns nullEvt ($0000). 

} 

Else (something returned from FindWindow other than those handled 
above): 

{ 

wmTaskData = returned value from FindWindow. 

Returns result from FindWindow. 

} 
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$180E TrackGoAway 

Tracks the mouse until the mouse button is released, highlighting the go-away region 
as long as the mouse location remains inside it and unhighlighting it when the mouse 
moves outside it. 

When there’s a mouse-down event in the go-away region of the specified window and 
the application is not using TaskMaster, the application should call TrackGoAway with 
startX and sfartKequal to the point where the mouse button was pressed (in global 
coordinates, as stored in the where field of the event record). 

The exact way a window’s go-away region is highlighted depends on its window 
definition procediue. If the user releases the mouse button while the cursor is inside 
the go-away region, TrackGoAway unhighlights the go-away region and returns TRUE 
(following which the application should eventually perform a CloseWindow). If the 
user releases the mouse button while the cursor is outside the go-away region, 
TrackGoAway returns FALSE (in which case the application should do nothing). 


Parameters 


Stack before call 


previous contents 


wordspace 


StartX 


startY 


— theWindowPtr 


Word—Space for result 
Word—Starting X coorditute 
Word—Starting Y coordinate 

Long—POINTER to window’s 

<—SP 


of cursor, 
of cursor, 

GrafPort 


in global coordinates 
in global coordinates 


Stack after call 


previous contents 
goAway 


Word—^BOOLEAN; TRUE if go-away selected when button released, 
<— SP FALSE if not 


Errors None 
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c 


extern pascal Boolean TrackGoAway(startX,startY,theWindowPtr) 


Integer startX; 

Integer startY; 

GrafPortPtr theWindowPtr; 

You can also use the following alternate form of the call: 
extern pascal Boolean TrackGoAway(start,theWindowPtr) 
Point start; 

GrafPortPtr theWindowPtr; 
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$260E TrackZoom 

Tracks the mouse until the mouse button is released, highlighting the zoom region as 
long as the mouse location remains inside it and unhighlighting it when the mouse 
moves outside it. 

When there’s a mouse-down event in the zoom region of the specified window and the 
application is not using TaskMaster, the application should call TrackZoom with 
stanXzad sfartTequal to the point where the mouse button was pressed (in global 
coordinates, as stored in the where field of the event record). 

The exact way a window’s zoom region is highlighted depends on its window 
definition procedure. If the mouse button is released inside the zoom region, 
TrackZoom unhighlights the zoom region and returns TRUE (following which the 
application should eventually perform a ZoomWindow). If the mouse button is 
released outside the zoom region, TrackZoom returns FALSE (in which case the 
application should do nothing). 


Parameters 


Stack before call 


previous contents 


wordspace 


startX 


startY 


— theWindowPtr 


Word—Space for result 
Word—Starting X coordinate 
Word—Starting Y coordinate 

Long—POINTER to window’s 

SP 


of cursor, in global 
of cursor, in global 

GrafPort 


coordinates 

coordinates 


Stack after call 


previous contents 
zoom 


Word—^BOOLEAN; TRUE if zoom region was selected, FALSE if not 

<— SP 
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Errors 


None 


C extern pascal Boolean Trac)cZoom(9tartX,startY,theWindowPtr) 

Integer startX; 

Integer startY; 

GrafPortPtr theWlndowPtr; 

You can also use the following alternate form of the call: 

extern pascal Boolean TrackZoom(start,theWindowPtr) 

Point start; 

GrafPortPtr theWindowPtr; 
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$3C0E Valid Rect 

Removes a specified rectangle from the update region of the window whose GrafPort is 
the current port and tells the Window Manger to cancel any updates accumulated for 
that rectangle. The rectangle is clipped to the window’s content region and is given in 
local coordinates. 


important 

This routine changes the coordinates you give it. Save the coordinates If you 
need to restore them later. 


Parameters 

Stack before call 
previous contents 

goodRectPtr — Long—POINTER to RECT specifying rectangle to be removed 

f-SP 


Stack after call 


previous contents 


<—SP 


Errors None 

C extern pascal void ValidRect(goodRectPtr) 

Rect *goodRectPtr; 
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$3D0E ValidRgn 

Removes a specified region from the update region of the window whose GrafPoit is 
the current port and teUs the Window Manger to cancel any updates accumulated for 
that region. The region is clipped to the window’s content region and is given in local 
coordinates. 


Important 

This routine changes the coordinates you give it. Save the coordinates if you 
need to restore them later. 


Parameters 

Stack before call 
previous contents 

— goodRgnHandle — Long—HANDLE to region to be subtracted from update region 

<—SP 


Stack after call 


previous contents 


SP 


Errors None 

C extern pascal void ValidRgn(goodRgnHandle) 

RgnHandle goodRgnHandle; 
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$530E WindDragRect 

Pulls a dotted outline of a specified rectangle around the screen, following the 
movements of the mouse until the mouse button is released. WindDragRect is a way 
of accessing the Control Manager DragRect routine. See the section “DragRect” in 
Chapter 4, “Control Manager,” in Volume 1 for more information. 

Parameters 


»tack before call 


previous contents 


— longspace — 

Long —Space for result 

— actionProcPtr — 

Long —POINTER to routine; NIL for default 

— dragPattemPtr — 

Long —POINTER to pattern to use for drag outline 

startX 

Word —coordinate of starting point, in global coordinates 

startY 

Word —Y coordinate of starting point, in global coordinates 

~ dragRectPtr — 

Long —POINTER to RECT data structure of rectangle to be dragged 

— HmitRectPtr 

Long —POINTER to RECT of limit rectangle 

— slopRectPtr — 

Long —POINTER to RECT of slop rectangle 

dragPlag 

Word —Bit flag customizing drag rectangle (see Figure 4-25 in Volume 1) 
4—SP 

Stack after call 


previous contents 


moveDelta — 

Long —High word = amount X changed; low word = amount Y changed 

<— SP 
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Errors 


None 


C 


extern pascal LongWord WindDragRect(actionProcPtr,dragPatternPtr 
startX,startY,dragRectPtr,limitRectPtr,slopRectPtr,dragFlag) 

VoidProcPtr actionProcPtr; 

Pattern dragPatternPtr; 

Integer startX; 

Integer startY; 

Rect *dragRectPtr; 

Rect *limitRectPtr; 

Rect *slopRectPtr; 

Word dragFlag; 

You can also use the following alternate form of the call; 

extern pascal LongWord WindDragRect(actionProcPtr,dragPatternPtr 
Start,dragRectPtr,limitRectPtr,slopRectPtr,dragFlag) 

VoidProcPtr actionProcPtr; 

Pattern dragPatternPtr; 

Point start; 

Rect *dragRectPtr; 


Rect *limitRectPtr; 
Rect *slopRectPtr; 
Word dragFlag; 
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$250E 

WindNewRes 

Closes the Window Manager’s GrafPort and opens a new GrafPort in the other Super 
Hi-Res resolution. However, the screen is not redrawn by the Window Manager in the 
new resolution. You can then call the RefreshDesktop routine when all resolution 
changes, such as changes to the desktop pattern and window colors, have been 
completed. 

You should call WindNewRes after the screen resolution has been changed. 

Parameters 

The stack is not affeaed by this call. There are no input or output parameters. 

Errors 

None 

C 

extern pascal void WindNewRes() 
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$S60E WindowGIobal 

Specifies a mask that determines how the Window Manager performs tasks. If 
windotvGlobalMask has bit 15 set to 1, the mask will be ANDed with the global flag. 
If uHndowGlobalMaskhzs bit 15 set to 0, the mask will be ORed with the global flag. 
WindowGIobal also returns the current state of the global flag in windowGlobalFlag. 


Important 

At the time of publication, all bits except 15 and 0 are reserved for future use. 


Parameters 


Stack before call 


previous contents 
wordspace 
WindotvGlobalMask 


Word—Space for result 
Word—Global mask (see Table 25-11) 
SP 


Stack after call 
previous contents 

windowGlobalFlag Word—Current state of window global flag (see Table 25-11) 

<— SP 

Errors None 

C extern pascal Word WlndowGlobal(windowGlobalMask) 

Word windowGlobalMask; 
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stopping window highlighting 

The only valid values for the window global mask at the time of publication are used 
to change the Window Manager’s normal highlighting procedure, as shown in 
Table 25-10. 

Table 25-10 

Window global mask values 


Value Description 


$0000 Flag does not change (used to retrieve current state of flag) 

$0001 Stop the Window Manager from highlighting and unhighlighting windows 
when NewWindow and CloseWindow calls are made 
$FFFE Return the Window Manager to normal highlighting operation 

Under normal circumstances, the Window Manager highlights and unhighlights 
windows appropriately when they become active or inactive. However, you may wish 
to suppress that highlighting in order to speed up window redrawing. For example, 
the following pseudocode sequence demonstrates one use of WindowGlobal: 

NewWindow(appropriate parameters) ; Put up a new window, which is 

; automatically highlighted. 

WindowGlobal($0001) ; Turn highlighting off, 

doAlertO ; Put up an alert window, allow the user 

/ to choose something, and close the 
; alert. Although the alert window is 
/ on top of the document window, the 
; document window remains highlighted. 
WindowGlobal($FFFE) ; Return the Window Manager to normal 

; highlighting operations. 

The value returned in uHndowGlobalFlag indicates the state of the flag after any 
changes have been made. The values at the time of publication are shown in 
Table 25-11. 

Tabid 25-11 

Window global flag values 


Value Description 


$0000 Normal highlighting off 
$0001 Normal highlighting on 
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$270E ZoomWindow 

Switches the size and position of a specified window between its current size and 
position and its maximum size. If the routine is called again before the specified 
window is moved or resized, the window will be resized and positioned to the size and 
position before the last ZoomWindow was performed. When a SizeWindow or 
MoveWindow is performed while a window is zoomed, the last size becomes the new 
size and position. 


Parameters 

Stack before call 
previous contents 

— theWindowPtr — Long—POINTER to window’s GrafPort 

<—SP 


Stack after call 

previous contents I 

|<—SP 

Errors None 

C extern pascal void ZoomWindow(theWindowPtr) 

GrafPortPtr theWindowPtr; 
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Window Manager summary 

This section briefly summarizes the constants, data stmctures, and tool set error 
codes contained in the Window Manager. 


Important 

These definitions are provided in the appropriate interface file. 


Table 25-12 

Window Manager constants 


Name Value Description 


Axis parameters 

wNoConstraint 

$0000 

No constraint on movement 

wHAxisOnly 

$0001 

Horizontal axis only 

wVAxisOnly 

$0002 

Vertical axis only 

Desktop commands 

FromDesk 

$00 

Subtract region from desktop 

ToDesk 

$01 

Add region to desktop 

GetDesktop 

$02 

Get handle to desktop region 

SetDesktop 

$03 

Set handle to desktop region 

GetDeskPat 

$04 

Address of pattern or drawing routine 

SetDeskPat 

$05 

Change address of pattern or drawing routine 

GetVisDesktop 

$06 

Get desktop region minus visible windows 

BackGroundRgn 

$07 

For drawing directly on desktop 

SendBehind values 

toBottom 

-2 

Send window to bottom 

topMost 

-1 

Make window frontmost 

bottomMost 

$0000 

Make window bottom 


(continued) 
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Table 25-12 (continued) 
Window Manager constants 


Name 

Value 

Description 

Task mask values 

tmMenuKey 

$0001 

Handle menu key events 

tmUpdate 

$0002 

Handle update events 

tmFindW 

$0004 

FindWindow called 

tmMenuSel 

$0008 

MenuSelect called 

tmOpenNDA 

$0010 

OpenNDA called 

tmSysClick 

$0020 

SystemClick called 

tmDragW 

$0040 

DragWindow called 

tmContent 

$0080 

Activate inactive window on click in content region 

tmClose 

$0100 

TrackGoAway called 

tmZoom 

$0200 

TrackZoom called 

tmGrow 

$0400 

GrowWindow called 

tmScroll 

$0800 

Enable scrolling and activate inactive window on 
click in scroll bar 

tmSpecial 

$1000 

Handle events in special menu items 

tmCRedraw 

$2000 

Redraw controls upon activate event 

tmlnactive 

$4000 

Allows selection of inactive menu items 

tminfo 

$8000 

Don't activate inactive window on click in 
information bar 

TaskMaster codes 

wInDesk 

$0010 

In Desktop 

wInMenuBar 

$0011 

In system menu bar 

wClickCalled 

$0012 

System click called 

wInContent 

$0013 

In content region 

wInDrag 

$0014 

In drag region 

wInGrow 

$0015 

In grow region, active window only 

wInGoAway 

$0016 

In go-away region, active window only 

wInZoom 

$0017 

In zoom region, active window only 

wininfo 

$0018 

In information bar 

wInSpecial 

$0019 

Item ID selected was 250-255 

wInDeskItem 

$001A 

Item ID selected was 1-249 

wInFrame 

$001B 

In Frame, but not on anything else 

wInactMenu 

$001C 

Inactive menu item selected 

wClosedNDA 

$001D 

Desk accessory closed 

wCalledSysEdit 

$00 IE 

Inactive menu item selected 

wInSysWindow 

$8000 

High-order bit set for system windows 
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Table 25-12 (continued) 
Window Manager constants 


Name 

Value 

Description 

varCode values 

wDraw 

$00 

Draw window frame command 

wHit 

$01 

Hit test command 

wCalcRgns 

$02 

Compute regions command 

wNew 

$03 

Initialization command 

wDispose 

$04 

Dispose command 

wFrame values 

fHilited 

$0001 

Window is highlighted 

f Zoomed 

$0002 

Window is zoomed 

fAllocated 

$0004 

Window record was allocated 

fCtlTie 

$0008 

State of window’s controk tied to state of window 

finfo 

$0010 

Window has an information bar 

fVis 

$0020 

Window is visible 

fQContent 

$0040 

Select window if mouseDownEvt in inactive 
window’s content 

fMove 

$0080 

Window can be dragged 

f Zoom 

$0100 

Window has a zoom box 

fFlex 

$0200 

Data height and width are flexible 

fGrow 

$0400 

Window has a size box 

fBScroll 

$0800 

Window has a horizontal scroll bar 

fRScroll 

$1000 

Window has a vertical scroll bar 

fAlert 

$2000 

Alert-type window frame 

fClose 

$4000 

Window has a close box 

fTitle 

$8000 

Window has a title bar 

Record sizes 

windSize 

$145 

Size of window record 

wmTaskRecSize 

$16 

Size of task record 
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Table 25-13 

Window Manager data structures 


Name 

Offset 

Type 

Definition 

WIndRec (window record) 

wNext $00 

GrafPortPtr 

Pointer to next window record 

port 

$04 

GrafPort 

Window’s port 

wPadding 

$AE 

16 bytes 

Space for possible future 

wStrucRgn 

$BE 

RgnHandle 

expansion 

Region of frame plus content 

wContRgn 

$C2 

RgnHandle 

Content region 

wUpdateRgn 

$C6 

RgnHandle 

Update region 

wControls 

$CA 

CtlRecHndl 

Window's control list 

wFrameCtrls 

$CE 

CtlRecHndl 

Window frame's control list 

wFrame 

$D2 

Word 

Bit flags 

WIndColor (window color table) 
frameColor $00 

Word 

Color of window frame 

titleColor 

$02 

Word 

Color of title and bar 

tBarColor 

$04 

Word 

Color and pattern of title bar 

growColor 

$06 

Word 

Color of grow box 

InfoColor 

$08 

Word 

Color of information bar 

Paramllst (NewWIndow parameter list) 
paramLength $00 Word 

Total number of bytes in 

wFrameBits 

$02 

Word 

parameter table 

Bit flag that describes window 

wTitle 

$04 

Pointer 

Pointer to window's title 

wRefCon 

$08 

LongWord 

Reserved for application use 

wZoom 

$0C 

Rect 

Size and positon of content 

wColor 

$14 

WindColorPtr 

Pointer to window's color table 

wYOrigin 

$18 

Integer 

Content's vertical origin 

wXOrigin 

$1A 

Integer 

Content's horizontal origin 

wDataH 

$1C 

Word 

Height of entire document 

wDataW 

$1E 

Word 

Width of entire document 

wMaxH 

$20 

Word 

Maximum height of content 

wMaxW 

$22 

Word 

allowed by GrowWindow 

Maximum width of content allowed 


by GrowWindow 
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Table 25-13 (continued) 

Window Manager data structures 


Name Offset Type Definition 


Paramllst (NewWindow parameter list) 


wScrollVer 

$24 

Word 

wScrollHor 

$26 

Word 

wPageVer 

$28 

Word 

wPageHor 

$2A 

Word 

wInfoRefCon 

$2C 

LongWord 

wInfoHeight 

$30 

Word 

wFrameDefProc 

$32 

LongProcPtr 

wInfoDefProc 

$36 

VoidProcPtr 

wContDefProc 

$3A 

VoidProcPtr 

wPosition 

$3E 

Reel 

wPlane 

$46 

GrafPortPtr 

wStorage 

$4A 

WindReePtr 

WmTaskRec (task 

record) 


wmWhat 

$00 

Word 

wmMessage 

$02 

LongWord 

wmWhen 

$06 

LongWord 

wmWhere 

$0A 

Point 

wmModifiers 

$0E 

Word 

wmTaskData 

$10 

LongWord 

wmTaskMask 

$14 

LongWord 


Number of pixels to scroll 
vertically when arrow is clicked 
Number of pixels to scroll 
horizontally when arrow is clicked 
Number of pixels to scroll 
vertically for page 
Number of pixels to scroll 
horizontally for page 
Value passed to draw information 
bar routine 

Height of information bar 
Pointer to standard window 
definition procedure 
Pointer to routine that draws the 
interior of the information bar 
Pointer to routine that draws the 
interior of the content region 
Window’s starting position and size 
Window’s starting plane 
Pointer to memory to use for 
window record 

Unchanged from event record 
Unchanged from event record 
Unchanged from event record 
Unchanged from event record 
Unchanged from event record 
TaskMaster return value 
TaskMaster feature mask 


Note: The actual assembly-language equates have a lowercase letter o in front of all the 
names given in this table. 
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Table 25-14 

Window Manager error codes 


Code Name Description 


$0E01 paramLenErr 
$0E02 allocateErr 
$0E03 taskMaskErr 


First word of parameter list is the wrong size 
Unable to allocate memory for window record 
Reserved bits not clear in wmTaskMask field of task 
record 
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Appendix A 


Writing Your Own 
Tool Set 


The Tool Locator system, which is flexible enough to allow you to write your own tool 

sets for use in your applications, supports both system tools and user tools. 

When writing your own tool set, the following must be kept in mind: 

■ Tool sets get control in full native mode. 

■ Work space should be dynamically assigned. Tool sets should not use any fixed 
RAM locations for work space; they should obtain their work space from the 
Memory Manager. This avoids memory conflicts, such as those caused by fixed 
usage of saeen holes. 

■ A simple interrupt environment should be supplied. Each function should 
increment or decrement the busy flag, be reentrant, or disable interrupts during 
execution. The most common approach is to use the busy flag. See Chapter 19, 
“Scheduler,” for more information. 

■ Before returning control to the caller, routines must restore the caller's execution 
environment. This includes the data bank register, the direct-page register, and 
any soft switches. 

■ Routines should not assume the presence of any operating system unless the 
operating system is directly relevant; for example, a routine that reads or writes a 
file, where other considerations demand that the file type be known anyway. 








structure of the Tool Locator 

The Tool Locator requires a few fixed RAM locations and no fixed ROM locations. 
All functions are accessed through the Tool Locator via their tool set number and 
function number. The Tool Locator uses the tool set number to find an entry in the 
tool pointer table (TPD. This table contains pointers to function pointer tables 
(FPTs). Each tool set has an FPT that contains pointers to the individual routines in 
the tool. The Tool Locator uses the function number to find the address of the 
routine being called. 

Each tool in ROM has an FPT in ROM. In ROM, there is also a TPT that points to all 
the FPTs in ROM. One fixed RAM location is used to point to this TPT in ROM. This 
location is initialized at power up and warm boot by the firmware. In this way, the 
address of the TPT in ROM does not ever have to be fixed. 

The TPT has the form shown in Table A-1. 

Table A-1 

Stricture of a TPT (tool pointer table) 

Item Length Description 


Count 

4 bytes 

Pointer to TS 1 FPT 

4 bytes 

Pointer to TS 2 FPT 

4 bytes 

Pointer to TS n FPT 

4 bytes 


Number of tool sets plus 1 
Pointer to FPT for tool set number 1 
Pointer to FPT for tool set number 2 

Pointer to FPT for tool set number n 


The FPT has the form shown in Table A-2. 


Table A-2 

Structure of an FPT (function pointer table) 


Item Length Description 


Count 

Address of FI -1 
Address of F2 -1 
Address of F3 -1 
Address of F4 -1 
Address of F5 -1 
Address of F6 -1 
Address of F7 -1 
Address of F8 -1 
Address of F9 -1 


4 bytes Number of routines plus 1 
4 bytes Pointer to Bootinit routine minus 1 
4 bytes Pointer to Startup routine minus 1 
4 bytes Pointer to ShutDown routine minus 1 
4 bytes Pointer to Version routine minus 1 
4 bytes Pointer to Reset routine minus 1 

4 bytes Pointer to Status routine minus 1 

4 bytes Pointer to reserved routine minus 1 

4 bytes Pointer to reserved routine minus 1 

4 bytes Pointer to first nonrequired routine minus 1 


Address of F« - 1 4 bytes 


Pointer to last nonrequired routine minus 1 
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Tool set numbers and function numbers 

Each system tool is assigned a permanent tool number. Assignment starts at one and 
continues with each successive integer. 

Each function within a tool set is assigned a permanent function number. For the 
functions within each tool, assignment starts at 1 and continues with each successive 
integer. Thus, each function has a unique, permanent identifier of the form 
itsNumJuncNum). Both tsNum and funcNum are 8-bit numbers. The tool set 
numbers assigned to the Apple tools are shown in Table 24-2 in Chapter 24, “Tool 
Locator.” 

For each tool set, certain standard routines must be present. Each tool set must have 
a boot initialization routine that is executed at boot time either by the ROM startup 
code or when the tool set is installed in the system. In addition, each tool set has an 
application Startup routine, an application ShutDown routine to allow an 
application to turn each tool on and off, a Version routine that returns information 
about the version of the tool, a Reset routine to be called when the system is reset, 
and a Status routine to indicate whether the tool set is active. 

All tools must return version information in the form of a word. The high byte of the 
word indicates the major release number (starting with 1). The low byte of the word 
indicates the minor release number (starting with 0). The most significant bit of the 
word indicates whether the code is an official release or a prototype (no distinction is 
made between alpha, beta, or other prototype releases). 

The standard routines are summarized in Table A-3. 

Table A-3 

Standard tool set routine numbers 
FuncNum Description 


1 Boot initialization function for each tool set 

2 Application startup function for each tool set 

3 Application shutdown function for each tool set 

4 Version information 

5 Reset 

6 Status 

7 Reserved for future use 

8 Reserved for future use 


Tooi set numbers and function numbers 
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Obtaining memory 

Tool sets are to obtain any memory they need dynamically (using as little fixed 
memory as possible) through the Memory Manager. To do that, a tool set needs 
some way to find the location of its data structures. The Tool Locator maintains a 
table of work area pointers for the individual tools. The work area pointer table 
(WAPT) is a table of pointers to the work areas of individual tools. 

In the WAPT, each tool will have an entry for its own use. Entries are assigned by tool 
set number (tool 04 has entry 04 and so on). A pointer to the WAPT is kept at a fixed 
memory location in RAM so that space for the table can be allocated dynamically. 

The Tool Locator system permanently reserves some space in bank $E1 for the 
purposes shown in Table A-4. 


Table A-4 

Tool Locator permanent RAM space 


Address 

Length 

Description 

$E103C0 

4 bytes 

Pointer to the active TPT. The pointer is to the ROM-based 
TPT if there are no RAM-based tool sets and no RAM-based 
ROM patches. Otherwise, it will point to a RAM-based TPT. 

$E103C4 

4 bytes 

Pointer to the active user’s TPT. This pointer is 0 initially, 
indicating that no user tools are present. 

$E103C8 

4 bytes 

Pointer to the WAPT. The WAPT parallels the TPT. Each 
WAPT entry is a pointer to a work area assigned to the 
corresponding tool set At startup time, each WAPT entry 
is set to 0, indicating no assigned work area. 

$E103CC 

4 bytes 

Pointer to the user’s Work Area Pointer Table CWAPTO. 

$E10000 

16 bytes 

Entry points to the dispatcher. 


This is the only RAM permanently reserved by the Tool Locator system. 
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Tool Locator system initialization 

Each tool set is initialized before use by application programs. Two types of 
initialization are needed: boot initialization and application initialization. Boot 
initialization occurs either at system startup time Oboot time) or, for tool sets loaded 
from disk, when the tool is installed. Regardless of the applications to be executed, 
the system calls the boot initialization function of every tool set. Thus, each tool set 
must have a boot initialization routine (JuncNum = 1), even if it does nothing. This 
function has no input or output parameters. 

Application initialization occurs during application execution. The application calls 
the application startup function (JuncNum = 2) of each tool set it will use. The 
application startup function performs the chores needed to start up the tool set so 
the application can use it. This function may have inputs and outputs, as defined by 
the individual tool set. 

The application shutdown function (JuncNum - 3) should be executed as soon as the 
application no longer needs to use the tool. The shutdown releases the resources 
used by the tool. As a precaution against applications forgetting to execute the 
shutdown function, the startup function should either execute the shutdown function 
itself or do something else to ensure a reasonable startup state. 

The provision of two initialization times reflects the needs of currently envisioned 
tools. On the one hand, for example, the Memory Manager requires boot time 
initialization because it must operate properly even before any application has been 
loaded. On the other hand, SANE needs to be initialized only if ^e system executes 
some application or desk accessory that uses it. Initializing only the tool sets that will 
be used saves resources, particularly RAM. 


Disk and RAM structure of tool sets 

System tool sets are load files kept in the TOOLS subdirectory of the SYSTEM 
directory. Their file type is $BA; each tool set begins with a function pointer table. 

User tool sets may be in any form; it is the responsibility of the application to 
properly load and install such tool sets. 


Disk and RAM structure of tool sets 
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Installing your tool set 

Before you make any calls to a user tool set, you must install it into the system. You 
do this by calling the Tool Locator routine SetTSPtr. SetTSPtr takes three inputs on 
the stack as follows: 


Stack before SetTSPtr 

Word—$0000 = system tool set, $8000 = user tool set 
Word—Tool set number of the tool set 

Long—POINTER to function pointer table for tool set 

<—SP 

When SetTSPtr is called, your tool is installed in the system and its boot initialization 
function call is executed. Hie following example illustrates installation of a sample 
user tool: 


previous contents 
userOrSystem 
tsNum 


JptPtr 


Install 


START 


clc 

xce 

php 


; Switch to full native mode and 
; save initial state 


rep #$30 


; 16-bit registers 


PushWord $8000 
PushWord #$23 
PushLong #CallTable 
SetTSPtr 


/ Signal a user tool 
; Put the tool number on the stack 
; Point to call table 


pip 

xce 

rts 

END 


; Restore machine state 
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CallTable 


START 


long (TheEnd-CallTable)/4 

long MyBootInit-1 
long MyStartUp-1 
long MyShutDown-l 
long MyVersion-1 
long MyReset-1 
long NotImp-1 
long NotImp-1 
long NotImp-1 

long FirstFunc-1 
long LastFunc-1 

TheEND 

END 

MyBootInit START ; Called when installed 

Ida #0 
clc 
rtl 
END 


MyStartUp START ; User passes me word containing location 

; to use in bank zero 

RTLl equ 1 

RTL2 equ RTLl+3 

ZPToUse equ RTL2+3 

ToolNum equ 5 ; Will be SP+5 just before SetWAP call 


Ida ZPToUse,s 
pea $8000 
phx 

pea 0 
pha 

Ida ToolNum,s 
and #$00FF 
sta ToolNum,s 
SetWAP 


Get caller's value 

Get ready to modify user tool tables 
Tool set number and function number - 
function number will be erased later 
High-order word is zero 
Low-order word is caller's value 
Get tool set number and function number 
Eliminate function number (MSB) 

Parameter now contains only tool set number 
Set our work area pointer 


Installing your tool set 
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; Next, the input parameter must be removed from the stack. 

; Do this by sliding the two return addresses up the stack by two bytes, 

; such that the most-significant word of the second-level return address 
; slides right into the spot previously occupied by the input parameter. 

; This isn't very difficult, because the two addresses occupy the same 
; number of words. 

Ida RTL2+l,s ; Catch upper two bytes of RTL2 

sta ZPToUse,s ; Write them over input parameter space 

Ida RTLl+2,s ; Catch MSB of RTLl and LSB of RTL2 

sta ZPToUse-2 

Ida RTLl 

sta RTLl+2 

/ The bytes at SP+1 and SP+2 (or RTLl and RTLl+1) are empty and may be pulled 



pla 

r 

as a single word! 


Ida #0 

clc 

r 

Report that no error occurred 


rtl 

r 

Done 


END 



/ 

MyShutDown 

START 

cmp #0 

beq Nevermind 
pea $8000 

f 

Clear out the WAPT entry 


txa 

f 

Tool set number and function number were 



r 

in X on entry 


and #$00FF 

f 

Eliminate function number (MSB) 


pha 

r 

Tell SetWap which entry to clear 


pea 0 

t 

and 


pea 0 

r 

zero the entry 


__SetWAP 



Nevermind 

ANOP 




Ida #0 




clc 




rtl 




END 



t ' “ ' 

MyVersion 

START 



RTLl 

equ 1 



RTL2 

equ RTLl+3 



VerNum 

equ RTL2+3 




Ida #$90 

• 

r 

Version 1.0 prototype 


sta VerNum,s 

Ida #0 

clc 

rtl 

END 

A-8 Appendix A: Writing Your Own Tooi Set 





MyReset START 

Ida #0 
clc 
rtl 
END 


t 

Not Imp 

START 






txa 

t 

Tool set number and 

function number 

were 



t 

in X on entry 




xba 

i 

Tool set number was 

in LSB, move to 

MSB 



i 

for error 




ora #$00FF 

t 

Easy way to put $FF 

in LSB as error 

code 


sec 

t 

Raise error flag 




rtl 






END 






FirstFunc START 


Ida #0 

cic 

rtl 

END 


LastFunc START 

Ida #0 

cic 

rtl 

END 


Notes 

The long macro deposits a 4-byte value in memory, low bytes first. 

The PushWord macro pushes a word onto the stack (either from a memory 
location or with a pea instruction if # is used). 

The PushLong macro pushes a long on the stack (either from memory 
or with two pea instructions if # is used). 


Disk and RAM structure of tool sets 
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Function execution environment 

when your function is called, the machine is in full native mode and the following 
three registers are set with specific information to make the function's job easier: 

■ A register = low-order word of entry in WAPT for tool 

■ Y register = high-order word of entry in WAPT for tool 

■ X register = function number and tool set number 


When the function is called, the stack looks like this: 


previous contents 


outputSpace 


inputl 


input2 


inputLast 


mi 


1 mi 

|<— SP 


rni 


Word or Long—Space for output 
Word or Long—^First input 

Word or Long—Second input 


Word or Long—Last input 
3 bytes—RTL address 
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Appendix B 


Tool Set 
Error Codes 


In Appendix B, the tool set error codes are listed and summarized in error number 
order. If a tool set error has not occurred, the carry flag (c flag) will not be set and 
the accumulator will contain $0000. 


Table B-1 

Tool set error codes 


Code Name 


System 

failure codes 

$0001 

pdosUnClmdIntErr 

$0004 

divByZeroErr 

$000A 

pdosVCBErr 

$000B 

pdosFCBErr 

$000C 

pdosBlkOErr 

$000D 

pdosIntShdwErr 

$0015 

segLoaderlErr 

$0017 

sPackageOErr 

$0018 

packagelErr 

$0019 

package2Err 

$001A 

packageSErr 

$00 IB 

package4Err 

$001C 

package5Err 

$001D 

package6Err 

$001E 

package7Err 

$0020 

packageBErr 

$0021 

package9Err 


Description 


Unclaimed interrupt CProDOS l6) 

Division by 0 

Volume control block unusable (ProDOS 16) 

File control block unusable (ProDOS l6) 

Block zero allocated illegally (ProDOS 16) 

Interrupt with I/O shadowing off (ProDOS l6) 

Segment Loader error 

Can’t load a package 

Can’t load a package 

Can’t load a package 

Can’t load a package 

Can’t load a package 

Can’t load a package 

Can’t load a package 

Can’t load a package 

Can’t load a package 

Can’t load a package 
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Table B-1 (continued) 
Tool set error codes 


Code Name 


Description 


System failure codes 

$0022 

packagelOErr 

$0023 

packagellErr 

$0024 

pac]cagel2Err 

$0025 

outOfMemErr 

$0026 

segLoader2Err 

$0027 

fMapTrshdErr 

$0028 

stkOvrFlwErr 

$0030 

psInstDiskErr 

$0032-53 

$0100 

stupVolMntErr 

Tool Locator codes 

$0001 

toolNotFoundErr 

$0002 

funcNotFoundErr 

$0110 

toolVersionErr 

$0111 

messNotFoundErr 

Memory Manager codes 

$0201 

memErr 

$0202 

emptyErr 

$0203 

notEmptyErr 

$0204 

lockErr 

$0205 

purgeErr 

$0206 

handleErr 

$0207 

idErr 

$0208 

attrErr 

Miscellaneous Tool Set codes 

$0301 

badInputErr 

$0302 

noDevParaunErr 

$0303 

taskInstlErr 

$0304 

noSigTaskErr 

$0305 

queueDmgdE rr 

$0306 

taskNtFdErr 

$0307 

firmTaskErr 

$0308 

hbQueueBadE rr 

$0309 

unCnctdDevErr 

$030B 

IdTagNtAvlErr 


Can't load a package 
Can't load a package 
Can't load a package 
Out of memory 
Segment Loader error 
File map destroyed 
Stack overflow 

Please insert disk (File Manager alerO 

Memory Manager errors 

Can’t mount system startup volume 

Specified tool set not found 
Specified routine not found 
Specified minimum version not found 
Specified message not found 

Unable to allocate block 
Illegal operation on an empty handle 
Empty handle expected for this operation 
Illegal operation on a locked or 
immovable block 

Attempt to purge an unpurgeable block 
Invalid handle 
Invalid user ID 

Illegal operation with specified attributes 

Bad input parameter 
No device for input parameter 
Specified task already in Heartbeat queue 
No signature detected in task header 
Damaged Heartbeat queue detected 
Specified task not in queue 
Unsuccessful firmware task 
Damaged HeartBeat queue detected 
Dispatch attempted to unconnected 
device 

No ID tag available 
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Table B-1 (continued) 
Tool set error codes 


Code 

Name 

Description 

QuickDraw II codes 


$0401 

alreadyinitialized 

QuickDraw II already initialized 

$0402 

cannotReset 

Never used 

$0403 

notInitialized 

QuickDraw II not initialized 

$0410 

screenReserved 

Screen reserved 

$0411 

badRect 

Invalid rectangle specified 

$0420 

notEqualChunkiness 

Chunkiness not equal 

$0430 

rgnAlreadyOpen 

Region already open 

$0431 

rgnNotOpen 

Region not open 

$0432 

rgnScanOverflow 

Region scan overflow 

$0433 

rgnFull 

Region full 

$0440 

polyAlreadyOpen 

Polygon already open 

$0441 

polyNotOpen 

Polygon not open 

$0442 

polyTooBig 

Polygon too big 

$0450 

badTableNum 

Invalid color table number 

$0451 

badColorNuin 

Invalid color number 

$0452 

badScanLine 

Invalid scan line number 

$04FF 

Not implemented 


Desk Manager codes 


$0510 

daNotFound 

Specified DA not available 

$0511 

notSysWindow 

Window pointer is not a pointer to a 
window owned by an NDA 

Event Manager codes 


$0601 

emDupStrtUpErr 

EMStartUp already called 

$0602 

emResetErr 

Can’t reset Event Manager 

$0603 

emNotActErr 

Event Manager not active 

$0604 

emBadEvtCodeErr 

Event code is greater than 15 

$0605 

emBadB11 nNoE rr 

Button number specified is not 0 or 1 

$0606 

emQSiz2LrgErr 

Size of event queue is greater than 3639 

$0607 

emNoMemQueueErr 

Insufficient memory available for queue 

$0681 

emBadEvt QE r r 

Event queue damaged—^fatal system error 

$0682 

emBadQHndlErr 

Queue handle damaged—fatal system error 

Sound Tool 

Set codes 


$0810 

noDOCFndErr 

No DOC or RAM found 

$0811 

docAddrRngErr 

DOC address range error 

$0812 

noSAppInitErr 

No SoundStartUp call made 

$0813 

in va IGenNuxnE r r 

Invalid generator number 

$0814 

synthModeErr 

Synthesizer mode error 

$0815 

genBusyErr 

Generator already in use 

$0817 

mstrIRQNotAssgnErr 

Master IRQ not assigned 

$0818 

sndAlreadySt rtErr 

Sound Tool Set already started 

$08FF 

unclaimedSndIntErr 

Unclaimed sound interrupt error (reported 
through System Failure Manager) 

(continued) 
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Table B-1 (continued) 
Tool set error codes 


Code 

Name 

Description 

Apple Desktop Bus Tool Set codes 


$0910 

cmndl ncomple t e 

Command not completed 

$0911 

cantSync 

Can’t synchronize with system 

$0982 

adbBusy 

ADB busy (command pending) 

$0983 

devNotAtAddr 

Device not present at address 

$0984 

srqListFull 

SRQ list full 

Integer Math Tool Set codes 


$0B01 

imBadlnptParam 

Bad input parameter 

$0B02 

imi llegaICha r 

Illegal character in string 

$0B03 

imOverflow 

Integer or Longint overflow 

$OB04 

imStrOverflow 

String overflow 

Text Tool Set codes 


$0C01 

badDevType 

Illegal device type 

$0C02 

badDevNum 

Illegal device number 

$0C03 

badMode 

Illegal operation 

$0C04 

unDefHW 

Undefined hardware error 

$0C05 

lostDev 

Lost device: device no longer on-line 

$0C06 

lostFile 

File no longer in diskette directory 

$0C07 

badTitle 

Illegal filename 

$0C08 

noRoom 

Insufficient space on specified diskette 

$0C09 

noDevice 

Specified volume not on-line 

$0C0A 

noFile 

Specified file not in directory of specified 
volume 

$0C0B 

dupFile 

Duplicate file: attempt to rewrite a file 
when a file of that name already exists 

$0C0C 

notClosed 

Attempt to open file that is already open 

$0C0D 

notOpen 

Attempt to access a closed file 

$0C0E 

badFormat 

Error in reading real or integer number 

$0C0F 

ringBuffOFlo 

Ring buffer overflow: characters arriving 
faster than the input buffer can accept them 

$0C10 

writeProtected 

Specified diskette is write-protected 

$0C40 

devErr 

Device error: device failed to complete a 
read or write correctly 

Window 

Manager codes 


$0E01 

paraitiLenErr 

First word of parameter list is the wrong 
size 

$0E02 

allocateErr 

Unable to allocate window record 

$0E03 

taskMaskErr 

Reserved bits not clear in wmTaskMask 
field of WmTaskRec 

Control Manager codes 


$1001 

winNo t S t a r t e dUp 

Window Manager not initialized 
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Description 


Table B-1 (continued) 
Tool set error codes 


Code 

Name 

Print Manager codes 

$1301 

mi ssingDriver 

$1302 

portNotOn 

$1303 

noPrintRecord 

$1304 

badLaserPrep 

$1305 

badLPFile 


$1306 

papConnNotOpen 

$1307 

papReadWriteErr 

$1321 

startUpAlreadyMade 

$1322 

in va 1 idC 11 Va 1 

LineEdit Tool Set codes 

$1401 

leDupStrtUpErr 

$1402 

leResetError 

$1403 

leNotActiveErr 

$1404 

leScrapErr 

Dialog Manager codes 

$150A 

badItemType 

$150B 

newltemFailed 

$150C 

itemNotFound 

$150D 

notModaIDialog 

Scrap Manager codes 

$1610 

badScrapType 

Font Manager codes 

$1B01 

fmDupStartUpErr 

$1B02 

fmResetErr 

$1B03 

fmNotActiveErr 

$1B04 

fmFamNotFndErr 

$1B05 

fmFontNtFndErr 

$1B06 

fmFontMemErr 

$1B07 

fmSysFontErr 

$1B08 

fmBadFamNumErr 

$1B09 

fmBadSizeErr 

$1B0A 

fmBadNameErr 

$1B0B 

fmMenuErr 

$1B0C 

fmScaleSizeErr 


Specified driver not in the DRIVERS 
subdirectory of the SYSTEM subdirectory 
Specified port not selected in the control 
panel 

No print record specified 
Version of LaserPrep file in LaserWriter is not 
compatible with this version of Print Manager 
Version of LaserPrep file in DRIVERS 
subdirectory of SYSTEM subdireaory is not 
compatible with this version of Print Manager 
Connection can’t be established with the 
LaserWriter 

Read-write error on the LaserWriter 
LLDStartUp call already made 
Invalid control value specified 


Inappropriate item type 
Item creation failed 
No such item 

Frontmost window not a modal dialog 
window 


No scrap of this type 

FMStartUp call already made 
Can’t reset the Font Manager 
Font Manager not active 
Family not found 
Font not found 
Font not in memory 
System font cannot be purgeable 
Illegal family number 
Illegal font size 
Illegal name length 
FixFontMenu never called 
Scaled size of font exceeds limits 


LEStartUp already called 
Can’t reset LineEdit 
LineEdit not active 
Desk saap too big to copy 
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Appendix C 


Tool Set Dependencies 
and Startup Order 


In Appendix C, the interdependencies of the tool sets are listed, and the order in 
whidi the tool sets must be started up is given. 


Tool set dependencies 

The Tool Locator (tool set number $01) does not depend on the presence of any of 
the other tool ^ts; rather, all of the other tool sets depend on the Tool Locator. 

Thus, Table C-1 begins with the Memory Manager (tool set number $02) and 
continues in tool set number order. 

❖ Note: The dependencies given in Table C-1 differ in some minor respects from 
those given in the individual tool set chapters. Those in Table C-1 are the most 
current at the time of publication; they were up to date as of October 1, 1987. For 
any further updates on the dependencies between the tool sets, check Apple IIGS 
Technical Note #12. 











Table C-1 

Tool set dependencies 


Tool set Tool set Minimum version 

number name needed 


Memory Manager (tool set number $02) depends on 


$01 

#01 

Tool Locator 

1.0 

Miscellaneous Tool Set (tool set nunnber $03) depends on 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

QuickDraw II (tool set number $04) depends on 

$01' 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

Desk Manager 

(tool set number $05) depends on 

$01 

#01 

Tool Locator 

1.2 

$02 

#02 

Memory Manager 

1.2 

$03 

#03 

Miscellaneous Tool Set 

1.2 

$04 

#04 

(QuickDraw n 

1.2 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

$0F 

#15 

Menu Manager 

1.3 

$10 

#16 

Control Manager 

1.3 

$14 

#20 

LineEdit Tool Set 

1.0 

$15 

#21 

Dialog Manager 

1.0 

$16 

#22 

Scrap Manager 

1.0 

Event Manager (tool set number $06) depends on 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

Scheduler (tool set number $07) depends on 


$01 

#01 

Tool Locator 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

Sound Tool Set (tool set number $08) depends on 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

Apple Desktop Bus Tool Set (tool set number $09) depends 

$01 

#01 

Tool Locator 

1.0 
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Table C-1 (continued) 
Tool set dependencies 


Tool set 
number 

Tool set 
name 

Minimum version 
needed 

SANE Tool Set (tool set number $0A) depends on 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

Integer Math Tool Set (tool set number $0B) depends on 

$01 

#01 

Tool Locator 

1.0 

Text Tool Set (tool set number $0C) depends on 

$01 

#01 

Tool Locator 

1.0 

Window Manager (tool set number $0E) depends on 

$01 

#01 

Tool Locator 

1.2 

$02 

#02 

Memory Manager 

1.2 

$03 

#03 

Miscellaneous Tool Set 

1.2 

$04 

#04 

(^uidtDrawII 

1.2 

$06 

#06 

Event Manager 

1.0 

Menu Manager (tool set number $0F) depends on 

$01 

#01 

Tool Locator 

1.2 

$02 

#02 

Memory Manager 

1.2 

$03 

#03 

Miscellaneous Tool Set 

1.2 

$04 

#04 

(QuickDraw n 

1.2 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

$10 

#16 

Control Manager 

1.3 

Control Manager (tool set number $10) depends on 

$01 

#01 

Tool Locator 

1.2 

$02 

#02 

Memory Manager 

1.2 

$03 

#03 

Miscellaneous Tool Set 

1.2 

$04 

#04 

(QuickDraw n 

1.2 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

QuickDraw II Auxiliary (tool set number $12) depends on 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$04 

#04 

(QuickDraw n 

1.2 


(continued) 
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Table C-1 (continued) 
Tool set dependencies 


Tool set Tool set Minimum version 

number name needed 


Print Manager (tool set number $13) depends on 


$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

2.0 

$03 

#03 

Miscellaneous Tool Set 

2.0 

$04 

#04 

(QuickDraw n 

2.0 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

$0F 

#15 

Menu Manager 

1.3 

$10 

#16 

Control Manager 

1.3 

$12 

#18 

(QuickDraw II Auxiliary 

1.0 

$14 

#20 

LineEdit Tool Set 

1.0 

$15 

#21 

Dialog Manager 

1.1 

$1B 

#27 

Font Manager 

1.0 

$1C 

#28 

List Manager 

1.0 

LineEdit Tool Set (tool set number $14) depends on 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$04 

#04 

QuickDraw n 

1.1 

$06 

#06 

Event Manager 

1.0 


❖ Note: If you are going to use the LEToScrap or 
LEFromScrap routines, the Scrap Manager must be 
loaded and started up. If you are going to use 
LETextBox2, you must load and start up the Integer 
Math Tool Set. 

Dialog Manager (tool set number $15) depends on 


$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$04 

#04 

QuickDraw n 

1.0 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

$0F 

#15 

Menu Manager 

1.3 

$10 

#16 

Control Manager 

1.3 

$14 

#20 

LineEdit Tool Set 

1.0 


Scrap Manager (tool set number $16) depends on 
$01 #01 Tool Locator 1.0 

$02 #02 Memory Manager 1.0 
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Table C-1 (continued) 

Tool set dependencies 

Tool set Tool sot Minimum version 

number name needed 


Standard File Tool Set (tool set number $17) depends on 


$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$04 

#04 

QuickDraw n 

1.0 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

$10 

#16 

Control Manager 

1.3 

$0F 

#15 

Menu Manager 

1.3 

$14 

#20 

LineEdit Tool Set 

1.0 

$15 

#21 

Dialog Manager 

1.1 

Font Manager (tool set number $1B) depends on 

$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$04 

#04 

(QuickDraw n 

1.1 


❖ Note: In addition to these tool sets, the ChooseFont 
routine requires 


$03 

#03 

Miscellaneous Tool Set 

1.2 

$0B 

#11 

Integer Math Tool Set 

1.0 

$0E 

#14 

Window Manager 

1.3 

$10 

#16 

Control Manager 

1.3 

$14 

#20 

LineEdit Tool Set 

1.0 

$15 

#21 

Dialog Manager 

1.0 

$1C 

#28 

List Manager 

1.0 

and the FixFontMenu routine requires 


$0F 

#15 

Menu Manager 

1.3 

$1C 

#28 

List Manager 

1.0 


If you are using the shadowed, outlined, or underlined 
text styles, QuickDraw II Auxiliary (tool set number $12) 
must be loaded and started up. 

List Manager (tool set number $1C) depends on 


$01 

#01 

Tool Locator 

1.0 

$02 

#02 

Memory Manager 

1.0 

$03 

#03 

Miscellaneous Tool Set 

1.0 

$04 

#04 

QuickDraw n 

1.0 

$06 

#06 

Event Manager 

1.0 

$0E 

#14 

Window Manager 

1.3 

$10 

#16 

Control Manager 

1.3 
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Tool set startup order 

Because each tool set depends on the presence of other tool sets, certain tool sets 
must be started up in a presaibed order for others to work. This order is shown in 
Table C-2, with tool sets lower on the list depending on the presence of all the tool 
sets higher on the list. Thus, all tool sets from the Tool Locator through the Control 
Manager must be started up before the Menu Manager. 

When you shut the tools down before you quit your application, you must shut them 
down in the reverse order from that in which they were started up; that is, the last one 
started up must be shut down first, the next-to-last started up shut down next, and so 
on. 

❖ Note: The startup order given in Table C-2 differs in some minor respects from that 
given in Chapter 2. Use the order given in Table C-2. For further updates, refer to 
Apple nos Technical Note #12. 


Table C-2 

Tool set startup order 


Toot set 
number 

Tool set 
name 

$01 

#01 

Tool Locator 

$02 

#02 

Memory Manager 

$03 

#03 

Miscellaneous Tool Set 

$04 

#04 

QuickDraw n 

$06 

#06 

Event Manager 

$0E 

#14 

Window Manager 

$10 

#16 

Control Manager 

$0F 

#15 

Menu Manager 

$14 

#20 

LineEdit Tool Set 

$15 

#21 

Dialog Manager 

$17 

#23 

Standard File Operations Tool Set 

$16 

#22 

Scrap Manager 

$05 

#05 

Desk Manager 

$1C 

#28 

List Manager 

$1B 

#27 

Font Manager 

$13 

#19 

Print Manager 


Note; If you are using QuickDraw II Auxiliary, it 
must be started up after QuickDraw II. 


You may assume that tool sets other than those listed in Table C-2 do not need to be 
started up in any particular order, that is, they may be started up or shut down at any 
time. 
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Appendix D 


List of Routines 
by Tool Set Number 
and Routine Number 


This appendix lists the tool set routines in tool set number and routine number 
order. The last two digits of the heaxadecimal number comprise the tool set 
number; the first two digits comprise the routine number. Thus, the number $0410 
means the routine numbered $04 in the tool set numbered $10, 

The list provided in this appendix can be useful, for example, when you are using a 
debugger and obtain the hexadecimal number, but not the name, of the routine. 
You can find the name by using this list and then looking up the name in the 
appropriate chapter. 







Table D-1 

Routines by tool set/routlne number 


Number Routine 


Tool Locator 
(Chapter 24) 

$0101 TLBootInit 

$0201 TLStartUp 

$0301 TLShutDown 

$0401 TLVersion 

$0501 TLReset 

$0601 TLStatus 

$0901 GetTSPtr 

$0A01 SetTSPtr 

$0B01 GetFuncPtr 

$0C01 GetWAP 

$0D01 SetWAP 

$0E01 LoadTools 

$0F01 LoadOneTool 

$ 1001 UnloadOneTool 

$1101 TLMountVolume 

$ 1201 TLTextMountVolume 

$ 1301 Sa veTextState 

$ 1401 RestoreTextState 

$ 1501 MessageCenter 

Memory Manager 
(Chapter 12) 

$0102 MMBootInit 

$0202 MMStartUp 

$0302 MMShutDown 

$0402 MMVersion 

$0502 MMReset 

$0602 MMStatus 

$0902 NewHandle 

$0A02 ReallocHandle 

$0B02 RestoreHandle 

$ 1002 DisposeHandle 

$1102 DisposeAll 

$ 1202 PurgeHandle 

$1302 PurgeAll 

$ 1802 GetHandleSize 

$ 1902 SetHandleSize 

$1A02 FindHandle 

$1B02 FreeMem 

$1C02 MaxBlock 


Number 

Routine 

Number 

Routine 

$1D02 

TotalMem 

$1D03 

GetMouseClamp 

$1E02 

CheckHandle 

$1E03 

PosMouse 

$1F02 

CompactMem 

$1F03 

ServeMouse 

$2002 

HLock 

$2003 

GetNewID 

$2102 

HLockAll 

$2103 

DeletelD 

$2202 

HUnlock 

$2203 

StatusID 

$2302 

HUnlockAll 

$2303 

IntSource 

$2402 

SetPurge 

$2403 

FWEntry 

$2502 

SetPurgeAll 

$2503 

GetTick 

$2802 

PtiToHand 

$2603 

PackBytes 

$2902 

HandToPtr 

$2703 

UnPackBytes 

$2A02 

HandToHand 

$2803 

Munger 

$2B02 

BlockMove 

$2903 

GetIRQEnable 

Miscellaneous Tool Set 
(Chaoter 14) 

$2A03 

$2B03 

SetAbsClamp 

GetAbsClamp 

$0103 

MTBootInit 

$2C03 

SysBeep 

$0203 

MTStartUp 

QuickDraw II 

$0303 

MTShutDown 

(Chapter 

16) 

$0403 

MTVersion 

$0104 

QDBootInit 

$0503 

MTReset 

$0204 

QDStartUp 

$0603 

MTStatus 

$0304 

QDShutDown 

$0903 

WriteBRam 

$0404 

QDVersion 

$0A03 

ReadBRam 

$0504 

QDReset 

$0B03 

WriteBParam 

$0604 

QDStatus 

$0C03 

ReadBParam 

$0904 

GetAddress 

$0D03 

ReadTimeHex 

$0A04 

GrafOn 

$0E03 

WriteTimeHex 

$0B04 

GrafOff 

$0F03 

ReadAsciiTime 

$0C04 

GetStandardSCB 

$1003 

SetVector 

$0D04 

InitColorTable 

$1103 

GetVector 

$0E04 

SetColorTable 

$1203 

SetHeartBeat 

$0F04 

GetColoiTable 

$1303 

DelHeartBeat 

$1004 

SetColorEntry 

$1403 

ClrHeartBeat 

$1104 

GetColorEntry 

$1503 

SysFailMgr 

$1204 

SetSCB 

$1603 

GetAddr 

$1304 

GetSCB 

$1703 

ReadMouse 

$1404 

SetAllSCBs 

$1803 

InitMouse 

$1504 

ClearScreen 

$1903 

SetMouse 

$1604 

SetMasterSCB 

$1A03 

HomeMouse 

$1704 

GetMasterSCB 

$1B03 

ClearMouse 

$1804 

OpenPort 

$1C03 

ClampMouse 

$1904 

InitPort 
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Table D-1 (continued) 

Routines by tool set/routIne number 


Number Routine Number Routine Number Routine 


QuickDraw ii 
(Chapter 16) 

$1A04 ClosePort 
$1B04 SetPort 
$1C04 GetPort 
$1D04 SetPortLoc 
$1E04 GetPortLoc 
$1F04 SetPortRect 
$2004 GetPortRect 
$2104 SetPortSize 
$2204 MovePortTo 
$2304 SetOrigin 
$2404 SetClip 
$2504 GetClip 
$2604 ClipRect 
$2704 HidePen 
$2804 ShowPen 
$2904 GetPen 
$2A04 SetPenState 
$2B04 GetPenState 
$2C04 SetPenSize 
$2D04 GetPenSize 
$2E04 SetPenMode 
$2F04 GetPenMode 
$3004 SetPenPat 
$3104 GetPenPat 
$3204 SetPenMask 
$3304 GetPenMask 
$3404 SetBackPat 
$3504 GetBackPat 
$3604 PenNormal 
$3704 SetSolidPenPat 
$3804 SetSolidBackPat 
$3904 SolidPattern 
$3A04 MoveTo 
$3B04 Move 
$3C04 LineTo 
$3D04 Line 
$3E04 SetPicSave 
$3F04 GetPicSave 
$4004 SetRgnSave 


$4104 

GetRgnSave 

$4204 

SetPolySave 

$4304 

GetPolySave 

$4404 

SetGrafProcs 

$4504 

GetGrafProcs 

$4604 

SetUserField 

$4704 

GetUserField 

$4804 

SetSysField 

$4904 

GetSysField 

$4A04 

SetRect 

$4B04 

OfFsetRect 

$4C04 

InsetRect 

$4D04 

SectRect 

$4E04 

UnionRect 

$4F04 

PtInRect 

$5004 

Pt2Rect 

$5104 

EqualRect 

$5204 

EmptyRect 

$5204 

NotEmptyRect 

$5304 

FrameRect 

$5404 

PaintRect 

$5504 

EraseRect 

$5604 

InvertRect 

$5704 

FillRect 

$5804 

FrameOval 

$5904 

PaintOval 

$5A04 

EraseOval 

$5B04 

InvertOval 

$5C04 

FillOval 

$5D04 

FrameRRect 

$5E04 

PaintRRect 

$5F04 

EraseRRect 

$6004 

InvertRRect 

$6104 

FillRRect 

$6204 

FrameArc 

$6304 

PaintArc 

$6404 

EraseArc 

$6504 

InvertArc 

$6604 

FillArc 

$6704 

NewRgn 

$6804 

DisposeRgn 


$6904 

CopyRgn 

$6A04 

SetEmptyRgn 

$6B04 

SetRectRgn 

$6C04 

RectRgn 

$6D04 

OpenRgn 

$6E04 

CloseRgn 

$6F04 

OffsetRgn 

$7004 

InsetRgn 

$7104 

SectRgn 

$7204 

UnionRgn 

$7304 

DiffRgn 

$7404 

XorRgn 

$7504 

PtInRgn 

$7604 

RectInRgn 

$7704 

EqualRgn 

$7804 

EmptyRgn 

$7904 

FrameRgn 

$7A04 

PaintRgn 

$7B04 

EraseRgn 

$7C04 

InvertRgn 

$7D04 

FillRgn 

$7E04 

ScrollRect 

$7F04 

PaintPixels 

$8004 

AddPt 

$8104 

SubPt 

$8204 

SetPt 

$8304 

EqualPt 

$8404 

LocalToGlobal 

$8504 

GlobalToLocal 

$8604 

Random 

$8704 

SetRandSeed 

$8804 

GetPixel 

$8904 

ScalePt 

$8A04 

MapPt 

$8B04 

MapRect 

$8C04 

MapRgn 

$8D04 

SetStdProcs 

$8E04 

SetCursor 

$8F04 

GetCursorAdr 
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Table D-1 (continued) 

Routines by tool set/routine number 


Number Routine Number Routine Number Routine 


QuickDraw II 
(Chapter 16) 

$9004 HideCursor 
$9104 ShowCursor 
$9204 ObscureCursor 
$9404 SetFont 
$9504 GetFont 
$9604 GetFontInfo 
$9704 GetFontGlobals 
$9804 SetFontFlags 
$9904 GetFontFlags 
$9A04 SetTextFace 
$9B04 GetTextFace 
$9C04 SetTextMode 
$9D04 GetTextMode 
$9E04 SetSpaceExtra 
$9F04 GetSpaceExtra 
$A004 SetForeColor 
$A104 GetForeColor 
$A204 SetBackColor 
$A304 GetBackColor 
$A404 DrawChar 
$A504 DrawString 
$A604 DrawCString 
$A704 DrawText 
$A804 CharWidth 
$A904 StringWidth 
$AA04 CStringWidth 
$AB04 TextWidth 
$AC04 CharBounds 
$AD04 StringBounds 
$AE04 CStringBounds 
$AF04 TextBounds 
$B004 SetArcRot 
$B104 GetArcRot 
$B204 SetSysFont 
$B304 GetSysFont 
$B404 SetVisRgn 
$B504 GetVisRgn 
$B604 SetIntUse 


$B704 

OpenPicture (Ch. 17) 

$B804 

PicComment (Ch. 17) 

$B904 

ClosePicture (Ch. 17) 

$BA04 

DrawPicture (Ch. 17) 

$BB04 

KillPicture (Ch. 17) 

$BC04 

FramePoly 

$BD04 

PaintPoly 

$BE04 

ErasePoly 

$BF04 

InvertPoly 

$C004 

FillPoly 

$C104 

OpenPoly 

$C204 

ClosePoly 

$C304 

KillPoly 

$C404 

OffsetPoly 

$C504 

MapPoly 

$C604 

SetClipHandle 

$C704 

GetClipHandle 

$C804 

SetVisHandle 

$C904 

GetVisHandle 

$CA04 

InitCursor 

$CB04 

SetBufDims 

$CC04 

ForceBufDims 

$CD04 

SaveBufDims 

$CE04 

RestoreBufDims 

$CF04 

GetFGSize 

$D004 

SetFontID 

$D104 

GetFontID 

$D204 

SelTextSize 

$D304 

GetTextSize 

$D404 

SetCharExtra 

$D504 

GetCharExtra 

$D604 

PPToPort 

$D704 

InflateTextBuffer 

$D804 

GetROMFont 

$D904 

GetFontLore 


Desk Manager 
(Chapter 5) 

$0105 

DeskBootInit 

$0205 

DeskStartUp 

$0305 

DeskShutDown 

$0405 

DeskVersion 

$0505 

DeskReset 

$0605 

DeskStatus 

$0905 

SaveScrn 

$0A05 

RestScrn 

$0B05 

Save All 

$0C05 

RestAll 

$0E05 

InstallNDA 

$0F05 

InstallCDA 

$1105 

ChooseCDA 

$1305 

SetDAStrPtr 

$1405 

GetDAStrPtr 

$1505 

OpenNDA 

$1605 

CloseNDA 

$1705 

SystemClick 

$1805 

SystemEdit 

$1905 

SystemTask 

$1A05 

SystemEvent 

$1B05 

GetNumNDAs 

$1C05 

CloseNDAByWinPtr 

$1D05 

CloseAllNDAs 

$1E05 

FixAppleMenu 
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Table D-1 (continued) 

Routines by tool set/routIne number 


Number 

Routine 

Number 

Routine 

Event Manager 

Sound Tool Set 

(Chapter 7) 

(Chapter 21) 

$0106 

EMBootInit 

$0108 

SoundBootlnit 

$0206 

EMStartUp 

$0208 

Sounds tartUp 

$0306 

EMShutDown 

$0308 

SoundShutDown 

$0406 

EMVersion 

$0408 

SoundVersion 

$0506 

EMReset 

$0508 

SoundReset 

$0606 

EMStatus 

$0608 

SoundToolStatus 

$0906 

DoWindows 

$0908 

WriteRamBlock 

$0A06 

GetNextEvent 

$0A08 

ReadRamBlock 

$0B06 

EventAvail 

$0B08 

GetTableAddress 

$0C06 

GetMouse 

$0C08 

GetSoundVolume 

$0D06 

Button 

$0D08 

SetSoundVolume 

$0E06 

StillDown 

$0E08 

FFStartSound 

$0F06 

WaitMouseUp 

$0F08 

FFStopSound 

$1006 

TickCount 

$1008 

FFSoundStatus 

$1106 

GetDblTime 

$1108 

FFGeneratorStatus 

$1206 

GetCaretTime 

$1208 

SetSoundMIRQV 

$1306 

Sets witch 

$1308 

SetUserSoundIRQV 

$1406 

PostEvent 

$1408 

FFSoundDoneStatus 

$1506 

FlushEvents 



$1606 

$1706 

GetOSEvent 

OSEventAvail 

Apple Desktop Bus Tool Set 
(Chapter 3) 

$0109 ADBBootInit 

$1806 

$1906 

SetEventMask 

FakeMouse 

$0209 

$0309 

ADBStartUp 

ADBShutDown 

Scheduler 


$0409 

ADBVersion 

(Chapter 19) 

$0509 

ADBReset 

$0107 

SchBootInit 

$0609 

ADBStatus 

$0207 

SchStartUp 

$0909 

Sendinfo 

$0307 

SchShutDown 

$0A09 

ReadKeyMicroData 

$0407 

SchVersion 

$0B09 

ReadKeyMicroMem 

$0507 

SchReset 

$0D09 

AsyncADBReceive 

$0607 

SchStatus 

$0E09 

SyncADBReceive 

$0907 

SchAddTask 

$0F09 

AbsOn 

$0A07 

SchFlush 

$1009 

AbsOff 



$1109 

ReadAbs 



$1209 

GetAbsScale 



$1309 

SetAbsScale 



$1409 

SRQPoll 



$1509 

SRQRemove 



$1609 

ClearSRQTable 


Number 

Routine 

SANE Tool Set 

(Chapter 18) 

$010A 

SANEBootInit 

$020A 

SANEStartUp 

$030A 

SANEShutDown 

$040A 

SANEVersion 

$050A 

SANEReset 

$060A 

SANEStatus 

$090A 

SANEFP 8 I 6 

$0A0A 

SANEDecStr8l6 

$0B0A 

SANEEleins8l6 

Integer Math Tool Set 

(Chapter 9) 

$010B 

IMBootInit 

$020B 

IMStartUp 

$030B 

IMShutDown 

$040B 

IMVersion 

$050B 

IMReset 

$060B 

IMStatus 

$090B 

Multiply 

$0A0B 

SDivide 

$0B0B 

UDivide 

$0C0B 

LongMul 

$0D0B 

LongDivide 

$0E0B 

FixRatio 

$0F0B 

FixMul 

$100B 

FracMul 

$110B 

FixDiv 

$120B 

FracDiv 

$130B 

FixRound 

$140B 

FracSqrt 

$150B 

FracCos 

$160B 

FracSin 

$170B 

FixATan2 

$180B 

HiWord 

$190B 

LoWord 

$1A0B 

LongZFix 

$1B0B 

Fix2Long 

$1C0B 

Fix2Frac 
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Table D-1 (continued) 

Routines by tool set/routIne number 


Number Routine 


Number Routine 


Number Routine 


Integer Math Tool Set 
(Chapter 9) 

$1D0B Frac2Fix 
$1E0B Fix2X 
$1F0B Frac2X 
$200B X2Fix 
$210B X2Frac 
$220B Int2Hex 
$230B Long2Hex 
$240B Hex2Int 
$250B Hex2Long 
$260B Int2Dec 
$270B Long2Dec 
$280B Dec2Int 
$290B Dec2Long 
$2A0B Hexit 

Text Tool Set 
(Chapter 23) 

$01OC TextBootInit 

$020C TextStartUp 
$030C TextShutDown 
$040C TextVersion 
$050C TextReset 
$060C TextStatus 
$090C SetInGlobals 
$OAOC SetOutGlobals 
$0B0C SetErrGlobals 
$0C0C GeUnGlobals 
$0D0C GetOutGlobals 
$0E0C GetErrGlobals 
$0F0C SetInputDevice 
$100C SetOutputDevice 
$ 11 OC SetErrorDevice 

$120C GetInputDevice 
$130C GetOutputDevice 
$140C GetErrorDevice 
$150C InitTextDev 
$160C CtITextDev 
$ 170C StatusTextDev 

$180C WriteChar 
$190C ErrWriteChar 


$1A0C 

WriteLine 

$1B0C 

ErrWriteLine 

SICOC 

WriteString 

$1D0C 

ErrWriteString 

$1E0C 

TextWriteBlock 

SlFOC 

ErrWriteBlock 

$200C 

WriteCString 

$210C 

ErrWriteCString 

$220C 

ReadChar 

$230C 

TextReadBlock 

$240C 

ReadLine 

Window Manager 

(Chapter 25) 

$010E 

WindBootInit 

$020E 

WindStartUp 

$030E 

WindShutDown 

$040E 

WindVersion 

$050E 

WindReset 

$060E 

WindStatus 

$090E 

NewWindow 

$0A0E 

CheckUpdate 

$0B0E 

CloseWindow 

$0C0E 

Desktop 

$0D0E 

SetWTitle 

$0E0E 

GetWTitle 

$0F0E 

SetFrameColor 

$100E 

GetFrameColor 

$110E 

SelectWindow 

$120E 

HideWindow 

$130E 

ShowWindow 

$140E 

SendBehind 

$150E 

FrontWindow 

$160E 

SetlnfoDraw 

$170E 

FindWindow 

$180E 

TrackGoAway 

$190E 

MoveWindow 

$1A0E 

DragWindow 

$1B0E 

GrowWindow 

$1C0E 

Size Window 

$1D0E 

TaskMaster 

SlEOE 

BeginUpdate 


SlFOE 

EndUpdate 

$200E 

GetWMgrPort 

$210E 

PinRect 

$220E 

Hilite Window 

$230E 

ShowHIde 

$240E 

BringToFront 

$250E 

WindNewRes 

$260E 

TrackZoom 

$270E 

ZoomWindow 

$280E 

SetWRefCon 

$290E 

GetWRefCon 

$2A0E 

GetNextWindow 

$2B0E 

GetWKind 

$2C0E 

GetWFrame 

$2D0E 

SetWFrame 

$2E0E 

GetStructRgn 

$2F0E 

GetContentRgn 

$300E 

GetUpdateRgn 

$310E 

GetDefProc 

$320E 

SetDefProc 

$330E 

GetWGontrols 

$340E 

SetOriginMask 

$350E 

GetInfoRefCon 

$360E 

SetInfoRefCon 

$370E 

GetZoomRect 

$380E 

SetZoomRect 

$390E 

RefreshDesktop 

$3A0E 

InvalRect 

$3B0E 

InvalRgn 

$3C0E 

ValidRect 

$3D0E 

ValidRgn 

$3E0E 

GetContentOrigin 

$3F0E 

SetContentOrigin 

$400E 

GetDataSize 

$410E 

SetDataSize 

$420E 

GetMaxGrow 

$430E 

SetMaxGrow 

$440E 

GetScroll 

$450E 

SetScroll 

$460E 

GetPage 

$470E 

SetPage 
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Table D-1 (continued) 


Routines by tool set/routlne number 

Number 

Routine 

Number 

Routine 

Number 

Routine 

Window Manager 

$160F 

GetMHandle 

Control Manager 

(Chapter 25) 

$170F 

SetBarColors 

(Chapter 4) 

$480E 

GetContentDraw 

$180F 

GetBarColors 

$0110 

CtlBoodnit 

$490E 

SetContentDraw 

$190F 

SetMTitleStart 

$0210 

CdStartUp 

$4A0E 

GetlnfoDraw 

$1A0F 

GelMTitleStart 

$0310 

CdShutDown 

$4B0E 

SetSys Window 

$1B0F 

GetMenuMgrPort 

$0410 

CdVersion 

$4C0E 

GetSysWFlag 

$1C0F 

CalcMenuSize 

$0510 

CdReset 

$4D0E 

StartDrawing 

$1D0F 

SetMTideWidth 

$ 06 l 0 

CdStatus 

$4E0E 

SetWindowIcons 

$1E0F 

GetMTitleWidth 

$0910 

NewControl 

$4F0E 

GetRectInfo 

$1F0F 

SetMenuFlag 

$0A10 

DisposeControl 

$500E 

StartInfoDrawing 

$200F 

GetMenuFlag 

$0B10 

KillControls 

$510E 

EndInfoDrawing 

$210F 

SetMenuTide 

$0C10 

SetCtlTide 

$520E 

GetFirslWindow 

$220F 

GetMenuTitle 

$0D10 

GetCdTide 

$530E 

WindDragRect 

$230F 

MenuGlobal 

$0E10 

HideControl 

$560E 

WindowGlobal 

$240F 

SetMItem 

$0F10 

ShowControl 

$570E 

SetContentOrigin2 

$250F 

GetMItem 

$1010 

DrawControls 

Menu Manaaer 

$260F 

SetMItemFlag 

$1110 

HiliteControl 

(Chapter 

13) 

$270F 

GetMItemFlag 

$1210 

CtiNewRes 

$010F 

MenuBootInit 

$280F 

SetMItemBlink 

$1310 

FindControl 

$020F 

MenuStartUp 

$290F 

MenuNewRes 

$1410 

TestControl 

$030F 

MenuShutDown 

$2A0F 

DrawMenuBar 

$1510 

TrackControl 

$040F 

MenuVersion 

$2B0F 

MenuSelect 

$1610 

MoveControl 

$050F 

MenuReset 

$2C0F 

HiliteMenu 

$1710 

DragControl 

$060F 

MenuStatus 

$2D0F 

NewMenu 

$1810 

SetCdIcons 

$090F 

MenuKey 

$2E0F 

DisposeMenu 

$1910 

SetCdValue 

$0A0F 

GetMenuBar 

$2F0F 

InitPalette 

$1A10 

GetCdValue 

$OBOF 

MenuRefresh 

$300F 

EnableMItem 

$1B10 

SetCdParams 

$0C0F 

FlashMenuBar 

$310F 

DisableMItem 

$1C10 

GetCdParams 

$0D0F 

InsertMenu 

$320F 

CheckMItem 

$1D10 

DragRect 

$0E0F 

DeleteMenu 

$330F 

SetMItemMark 

$1E10 

GrowSiae 

$0F0F 

InsertMItem 

$340F 

GetMItemMark 

$1F10 

GetCdDPage 

$100F 

DeleteMItem 

$350F 

SetMItemStyle 

$2010 

SetCdAcdon 

$110F 

GetSysBar 

$360F 

GetMItemStyle 

$2110 

GetCdAcdon 

$120F 

SetSysBar 

$370F 

SetMenuID 

$2210 

SetCtlRefCon 

$130F 

FixMenuBar 

$380F 

SetMItemID 

$2310 

GetCdRefCon 

$140F 

CountMItems 

$390F 

SetMenuBar 

$2410 

EraseControl 

$150F 

NewMenuBar 

$3A0F 

SetMItemName 

$2510 

DrawOneCtl 


(continued) 
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Tabid D-1 (continued) 

Routines by tool set/routlne number 


Number 

Routine 

Number 

Routine 

Number 

Routine 

Loader (not documented In this 

Print Manager 

LineEdlt Tool Set 

manual; see Apple liGS ProDOS 16 

(Chapter 

15) 

(Chapter 

10) 

Reference) 

$0113 

PMBootInit 

$0114 

LEBootInit 

$0111 

Loaderlnitialization 

$0213 

PMStartUp 

$0214 

LEStartUp 

$0211 

LoaderStartUp 

$0313 

PMShutDown 

$0314 

LEShutDown 

$0311 

LoaderShutDown 

$0413 

PMVersion 

$0414 

LEVersion 

$0411 

LoaderVersion 

$0513 

PMReset 

$0514 

LEReset 

$0511 

LoaderReset 

$0613 

PMStatus 

$0614 

LEStatus 

$0611 

Loaders tatus^ 

$0913 

PrDefault 

$0914 

LENew 

$0911 

InitialLoad 

$0A13 

PrValidate 

$0A14 

LEDispose 

$0A11 

Restart 

$0B13 

PrStlDialog 

$0B14 

LESetText 

$0B11 

LoadSegNum 

$0C13 

PrJobDialog 

$0C14 

LEIdle 

$0C11 

UnloadSegNum 

$0D13 

PrPixelMap 

$0D14 

LECIick 

$0D11 

LoadSegName 

$0E13 

PrOpenDoc 

$0E14 

LESetSelect 

$0E11 

UnloadSeg 

$0F13 

PrCloseDoc 

$0F14 

LEActivate 

$0F11 

GetLoadSegInfo 

$1013 

PrOpenPage 

$1014 

LEDeactivate 

$1011 

GetUserlD 

$1113 

PrClosePage 

$1114 

LEKey 

$1111 

LGetPathname 

$1213 

PrPicFile 

$1214 

LECut 

$1211 

UserShutDown 

$1413 

PrError 

$1314 

LECopy 

QuickDraw Auxiliary 

$1513 

PrSetError 

$1414 

LEPaste 

(Chapter 

17) 

$1613 

PrChoosePrinter 

$1514 

LEDelete 

$0112 

QDAuxBootInit 

$2313 

PrDriverVer 

$1614 

LEInsert 

$0212 

QDAuxStartUp 

$2413 

PrPortVer 

$1714 

LEUpdate 

$0312 

QDAuxShutDown 



$1814 

LETextBox 

$0412 

QDAuxVersion 



$1914 

LEFromScrap 

$0512 

QDAuxReset 



$1A14 

LEToScrap 

$0612 

QDAuxStatus 



$1B14 

LEScrapHandle 

$0912 

CopyPixels 



$1C14 

LEGetScrapLen 

$0A12 

WaitCursor 



$1D14 

LESetScrapLen 

$0B12 

Drawicon 



$1E14 

LESetHilite 





$1F14 

LESetCaret 





$2014 

LETextBox2 





$2114 

LESetJust 





$2214 

LEGetTextHand 





$2314 

LEGetTextLen 
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Table D-1 (continued) 

Routines by tool set/routine number 


Number Routine 


Number Routine 


Number Routine 


Dialog Manager 

(Chapter 6) 

$0115 

DialogBootInit 

$0215 

DialogStartUp 

$0315 

DialogShutDown 

$0415 

DialogVersion 

$0515 

DialogReset 

$0615 

DialogStatus 

$0915 

ErrorSound 

$0A15 

NewModalDialog 

$0B15 

NewModelessDialog 

$0C15 

CloseDialog 

$0D15 

NewDItem 

$0E15 

RemoveDItem 

$0F15 

ModalDialog 

$1015 

IsDialogEvent 

$1115 

DialogSelect 

$1215 

DlgCut 

$1315 

DlgCopy 

$1415 

DlgPaste 

$1515 

DlgDelete 

$1615 

DrawDialog 

$1715 

Alert 

$1815 

StopAlert 

$1915 

NoteAlert 

$1A15 

CautionAlert 

$1B15 

ParamText 

$1C15 

SetDAFont 

$1E15 

GetControlDItem 

$1F15 

GetIText 

$2015 

SetIText 

$2115 

SellText 

$2115 

SelectIText 

$2215 

HideDItem 

$2315 

ShowDItem 

$2415 

FindDItem 

$2515 

UpdateDialog 

$2615 

GetDItemType 


$2715 

SetDItemType 

$2815 

GetDItemBox 

$2915 

SetDItemBox 

$2A15 

GetFirstDItem 

$2B15 

GetNextDItem 

$2C15 

ModalDialog2 

$2E15 

GetDItemValue 

$2F15 

SetDItemValue 

$3215 

GetNewModalDialog 

$3315 

GetNewDItem 

$3415 

GetAlertStage 

$3515 

ResetAlertStage 

$3615 

DefaultFilter 

$3715 

GetDefButton 

$3815 

SetDefButton 

$3915 

DisableDItem 

$3A15 

EnableDItem 

Scrap Manager 

(Chapter 20) 

$0116 

ScrapBootlnit 

$0216 

ScrapStartUp 

$0316 

ScrapShutDown 

$0416 

ScrapVersion 

$0516 

ScrapReset 

$06l6 

ScrapStatus 

$0916 

UnloadScrap 

$0A16 

LoadScrap 

$0B16 

ZeroScrap 

$0C16 

PutScrap 

$0D16 

GetScrap 

$0E16 

GetScrapHandle 

$0F16 

GetScrapSize 

$1016 

GetScrapPath 

$1116 

SetScrapPath 

$1216 

GetScrapCount 

$1316 

GetScrapState 


Standard File Operations 

Tool Set (Chapter 22) 

$0117 

SFBootInit 

$0217 

SFStartUp 

$0317 

SFShutDown 

$0417 

SFVersion 

$0517 

SFReset 

$0617 

SFStatus 

$0917 

SFGetFile 

$0A17 

SFPutFile 

$0B17 

SFPGetFile 

$0C17 

SFPPutFile 

$0D17 

SFAllCaps 

Note Synthesizer (not 
documented in this manual) 

$0119 

NSBootInit 

$0219 

NSStartUp 

$0319 

NSShutDown 

$0419 

NSVersion 

$0519 

NSReset 

$0619 

NSStatus 

$0919 

AllocGen 

$0A19 

DeallocGeri 

$0B19 

NoteOn 

$0C19 

NoteOff 

$0D19 

AllNotesOff 


(continued) 
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Table D-1 (continued) 

Routines by tool set/routIne number 


Number Routine 

Note Sequencer (not 
documented In this manual) 
$011A SeqBootInit 

$021A SeqStartUp 

$031A SeqShutDown 

$041A SeqVersion 

$051A SeqReset 

$06lA SeqStatus 
$091A Setlncr 
$0A1A SeqBootInit 
$0A1A Clearlncr 
$0B1A GetTimer 
$0C1A GetLoc 
$0D1A AllNotesOff 
$0E1A SetTrkInfo 
$0F1A StartSeq 
$101A StepSeq 

$ 111A StopSeq 

$121A SeUnstTable 
$131A Startlnts 
$141A Stopints 


Number Routine 

Font Manager 
(Chapter 8) 

$01 IB FMBootInit 

$02 IB FMStartUp 

$03 IB FMShutDown 

$04 IB FMVersion 

$05 IB FMReset 

$06lB FMStatus 
$09 IB CountFamilies 

$0A1B FindFamily 
$0B1B GetFamInfo 
$0C1B GetFamNum 
$0D1B AddFamily 
$0E1B InstallFont 
$0F1B SetPurgeStat 
$101B CountFonts 
$ 111B FindFontStats 

$12IB LoadFont 

$13 IB LoadSysFont 

$141B AddFontVar 
$151B FixFontMenu 
$161B ChooseFont 
$171B IteinID2FamNum 
$181B FMSetSysFont 
$191B FMGetSysFID 
$1A1B FMGetCurHD 
$1B1B FamNum2ItemID 


Number Routine 

List Manager 
(Chapter 11) 

$011C ListBootInit 

$021C ListStartup 
$031C ListShutDown 
$041C ListVersion 
$051C ListReset 
$06lC ListStatus 
$091C CreateList 
$0A1C SortList 
$0B1C NextMember 
$0C1C DrawMember 
$0D1C SelectMember 
$0E1C GetListDefFroc 
$0F1C ResetMember 
$101C NewList 
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Glossary 


absolute: Said of a load segment or other 
program code that must be loaded at a specific 
address in memory and never moved. Compare 

relocatable. 

absolute addressing: An addressing mode in 
which instruction operands are interpreted as 
literal addresses. 

absolute clamps: Values that establish the 
minimum and maximum X and Y coordinates for 
alternative pointing devices. 

access, access byte: An attribute of a ProDOS 
file that controls whether the file may be read 
from, written to, renamed, or backed up. 

accumulator: The register in a computer's 
central processor or microprocessor where 
most computations are performed. Also called 
A register. 

activate: To make active. A control or window 
may be activated. Compare enable. 

activate event: A window event that occurs when 
a window is made either active or inactive. 

active: Able to respond to the user's mouse or 
keyboard actions. Controls and windows that are 
active are displayed differently than inactive 
items. 

ADB: See Apple Desktop Bus. 

ADB commands: Commands that are issued to 
the Apple Desktop Bus. These are not the same as 
Apple Desktop Bus Tool Set routines; rather, the 
tool set routines often include an ADB command 
as a parameter. The Apple Desktop Bus Tool Set 
then interprets and issues the ADB command. 


alert: A warning or report of an error in the form 
of an alert box, a sound from the computer's 
speaker, or both. 

alert box: A special type of dialog box that 
appears on the screen to give a warning or to 
report an error message during use of an 
application. 

alert sound: A sound generated by a sound 
procedure that emits a tone or sequence of tones 
when the user is to be alerted of a condition. 

alert stage: One of four stages that correspond to 
consecutive occurrences of an alert. 

alert template: A data structure that conatains 
an alert ID, a RECT determining the alert window's 
size and location, information about what should 
happen at each stage of the alert, and a list of 
pointers to the item templates. 

alert window: The window in which an alert box 
appears. One of the two predefined window 
formats. Compare document window. 

alternative pointing devices: A device, such as 
a graphics tablet or trackball, used instead of the 
mouse. 

Apple Desktop Bus (ADB): An input bus, with 
its own protocol and electrical characteristics, that 
provides a method of connecting input devices 
such as keyboards and mice with personal 
computers. 

Apple Desktop Bus Tool Set: The Apple IIGS 
tool set that facilitates an application's interaction 
with devices connected to the Apple Desktop Bus. 
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Apple key: A modifier key on the Apple IIGS 
keyboard, marked with both an Apple icon and a 
spinner, the icon used on the equivalent key on 
some Macintosh keyboards. It performs the same 
functions as the open Apple key on standard 
Apple II machines. 

AppleTalk network: A local area network 
developed by Apple Computer, Inc. 

Apple n: A family of computers, including the 
original Apple H, the Apple II Plus, the Apple lie, 
the Apple He, and the Apple IIGS. Compare 

standard Apple n. 

Apple n Plus: A personal computer in the 
Apple n family with expansion slots that allow the 
user to enhance the computer's capabilities with 
peripheral cards. 

Apple He: A transportable personal computer in 
the Apple II family, with a disk drive, serial ports, 
and 80-column display capability built in. 

Apple He: A personal computer in the Apple II 
family, with seven expansion slots and an auxiliary 
memory slot that allow the user to enhance the 
computer's capabilities with peripheral memory 
and video enhancement cards. 

Apple IIGS: The most advanced computer in the 
Apple II family. It features expanded memory, 
advanced sound and graphics, and the Apple IIGS 
Toolbox of programming routines. 

Apple IIGS Programmer’s Workshop: See 
APW. 

Apple IIGS Toolbox: An extensive set of routines 
that facilitates writing desktop applications and 
provides easy program access to many Apple IIGS 
hardware and firmware features. Functions within 
the toolbox are grouped into tool sets. 

application: A stand-alone program that 
performs a specific function, such as word 
processing, drawing, or telecommunications. 
Compare, for example, desk accessory, device 
driven 


application event: Any of four types of events 
available for applications to define and respond to 
as desired. 

application prefix: The ProDOS l6 prefix 
number 1/. It specifies the directory of the 
currently running application. 

application window: A window in which an 
application's document appears. 

APW (Apple IIGS Programmer’s 
Workshop): A multilanguage development 
environment for writing Apple IIGS desktop 
applications. 

APW Assembler; The 65816 assembly-language 
assembler provided with the Apple IIGS 
Programmer's Workshop. 

APW C Compiler: The C-language compiler 
provided with the Apple IIGS Programmer's 
Workshop. 

APW Shell: The programming environment of 
the Apple IIGS Programmer's Workshop. It 
provides facilities for file manipulation and 
program execution, and supports shell 
applications. 

arbitrary mode: In the List Manager, a selection 
mode that allows the user to select members in a 
list without deselecting already-selected members. 

arc: A portion of an oval; one of the fundamental 
shapes drawn by QuickDraw II. 

A register: See accumulator, 

ascent: In a font, the distance between the base 
line and the ascent line. 

ascent line: A horizontal line that coincides with 
the tops of the tallest characters in a font. See also 

base line, descent line. 
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ASCII! Acronym for American Standard Code 
for Information Interchange, pronounced 
“ASK-ee.” A code in which the numbers from 0 to 
127 stand for text characters. ASCII code is used to 
represent text inside a computer and to transmit 
text between computers or between a computer 
and a peripheral device. 

assembler: A language translator that converts a 
program written in assembly language into an 
equivalent program in machine language. 

AsyncADBRecelve completion routine: Used 
in conjunction with the ADB Tool Set routine 
AsyncADBReoeive, the completion routine 
obtains ADB data from a buffer. Compare SRQ 
list completion routine. 

attributes word: Determines how memory 
blocks are allocated and maintained. Most of the 
attributes are defined at allocation time and can’t 
be changed after that; other attributes can be 
modified after allocation. 

auto-key: A keyboard feature and an event type, 
in which a key being held down continuously is 
interpreted as a rapid series of identical 
keystrokes. 

auxID: A subfield of the user ID. An application 
may place any value it wishes into the auxID field. 

auxiliary type: A secondary classification of 
ProDOS files. A file’s auxiliary-type field may 
contain information of use to the applications that 
read it. Compare file type. 

available font: A font that the Pont Manager can 
use because the font is the ROM font, or a font in 
the FONTS subdirectory, or a font that the 
application has added with the Font Manager 
routine AddFontVar. 

background: The pixels within a character or 
other saeen object that are not part of the object 
itself. 

background colon The color of background 
pixels in text; by default it is black. 


background pattern: The pattern QuickDraw II 
uses to erase objects on the screen. 

background pixels: In a character image, the 
pixels that are not part of the character itself; that 
is, all pixels in the character bounds rectangle that 
are not foreground pixels. 

background procedure: A procedure run by the 
Print Manager whenever the Print Manager has 
directed output to the printer and is waiting for the 
printer to finish. 

bank: A 64K (65,536-byte) portion of the 
Apple IIGS internal memory. An individual bank is 
specified by the value of the 65C816 
microprocessor’s bank register. 

bank $00: The first bank of memory in the 
Apple IIGS. In emulation mode, it is equivalent to 
main memory in an Apple lie or Apple IIc 
computer. 

base family: A font family is a base family if it is 
the ROM font or if a plain-styled example of the 
family can be found among the fonts in the FONTS 
subdirectory. 

base height: In the LineEdit Tool Set, the 
distance between the top of the destination 
rectangle and the base line. This controls where 
the text is drawn. 

base llijie: A horizontal line that coincides with 
the bottom of the main body of each character in a 
font. Character descenders extend below the base 
line. 

BASIC: Acronym for Beginners All-purpose 
Symbolic Instruction Code. BASIC is a high-level 
programming language designed to be easy to 
learn. 

best-fit font algorithm: The algorithm that the 
Font Manager routine InstallFont uses to look for a 
font that matches a given set of specifications. 

bit: A contraction of binary digit, the smallest 
representation of data in a digital computer. 


Glossary 
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bit plane: A method of representing images in 
computer memory. In a bit plane, consecutive bits 
in memory specify adjacent pixels in the image; if 
more than one bit is required to completely 
specify the state of a pixel, more than one bit 
plane is used for the image. Compare chunky 
pixels. 

block: (1) A unit of data storage or transfer, 
typically 512 bytes. (2) A contiguous region of 
computer memory of arbitrary size, allocated by 
the Memory Manager. Also called memory 
block. 

block device; A device that transfers data to or 
from a computer in multiples of 1 block (512 bytes) 
of characters at a time. Disk drives are block 
devices. Also called block I/O device. 

block I/O device: See block device. 

Boolean logic: A mathematical system in which 
every expression evaluates to one of two values, 
usually referred to as TRUE or FALSE. 

Boolean variable: A variable that can have one 
of two values, usually referred to as TRUE or 
FALSE. 

bottom scroll bar: The scroll bar the user selects 
to scroll horizontally through the data in a 
window. 

boimdary rectangle: A rectangle, defined as 
part of a QuickDraw II locinfo record, that 
encloses the active area of the pixel image and 
imposes a coordinate system on it Its top left 
corner is always aligned on the first pixel in the 
pixel map. 

houndsRect: The GrafPort field that defines the 
port's boundary rectangle. 

buffer: A holding area of the computer's 
memory where information can be stored by one 
program or device and then read, perhaps at a 
different rate, by another; for example, a print 
buffer. 


busy flag: A feature that informs the Scheduler 
whether a currently needed resource is busy or 
available. 

button: (1) A pushbutton-like image in dialog 
boxes where the user clicks to designate, confirm, 
or cancel an action. See also check box, radio 
button. (2) A button on a mouse or other pointing 
device. See also mouse button. 

byte: A unit of information consisting of 8 bits. A 
byte can have any value between 0 and 255, which 
may represent an instruction, a letter, a number, a 
punctuation mark, or another character. See also 

bit, kilobyte, megabyte* 

C: A high-level programming language. One of 
the languages available for the Apple IIGS 
Programmer's Workshop. 

cancel: To stop an operation, such as the setting 
of page-setup values in a dialog box, without 
saving any results produced up to that point. 

Cancel: One of two predefined item ID numbers 
for dialog box buttons (Cancel = 2). Compare OK. 

caret: A symbol that indicates where something 
should or will be inserted in text On the screen it 
designates the insertion point, and is usually a 
vertical bar (I). 

carry flag: A status bit in the microprocessor 
indicating whether an accumulator calculation has 
resulted in a carry out of the register. Also called 
cflag. 

CDA: See classic desk accessory. 

CDA menu: The menu on which classic desk 
accessories are listed; the user selects the menu by 
pressing Control-Apple-Escape. See also classic 
desk accessory. 

c flag: See carry flag. 
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character: (1) Any symbol that has a widely 
understood meaning and thus can convey 
information. Some characters—^such as letters, 
numbers, and punctuation—can be displayed on 
the monitor screen and printed on a printer. Most 
characters are represented in the computer as 
1-byte values. (2) In QuickDraw II, a single ASCII 
character. 

character bounds rectangle: The rectangle that 
determines the extent of the background pixels of a 
character. 

character bounds width: The width of a 
character's character bounds reaangle. 

character device: A device that transfers data to 
or from a computer as a stream of individual 
characters. Keyboards and printers are character 
devices. 

character image: The part of a font strike that 
represents a character in a font. 

character image width: The number of 
columns in a character image. 

character origin: The point on the base line 
used as a reference location for drawing a 
character. 

character position: An index into LineEdit text, 
with position 0 corresponding to the first 
character. 

character rectangle: A rectangle that encloses a 
charaaer image. Its width is equal to the image 
width of the character; its height is equal to the 
character height. 

character width: The number of pixels the pen 
position is to be advanced after the character is 
drawn. 

check box: A small box associated with an 
option in a dialog box. When the user clicks the 
check box, that may change the option or affect 
related options. See also radio button* 


Choose Printer dialog box: A Print Manager 
dialog box that lets the user select a printer or port 
for printing. 

chunkiness: The number of bits required to 
describe the state of a pixel in a pixel image. 

chunky pixels: A method of representing 
images in computer memory. In chunky pixel 
organization, a number of consecutive bits in 
memory combine to specify the state of a single 
pixel in the image. Consecutive grxyups of bits (the 
size of the group is equal to the image's 
chunkiness) define adjacent pixels in the image. 
Compare bit plane* 

clamp values: The X- and Y-limits, in terms of 
pixels, on cursor position controlled by mouse 
movement. 

classic desk accessory (CDA): Desk accessories 
designed to execute in a nondesktop-, nonevent- 
based environment. Compare new desk 
accessory* 

click: To position the pointer on something, and 
then to press and quickly release the mouse or 
alternative pointing device's button. 

clip: To restrict drawing to within a particular 
boundary; any drawing attempted outside that 
boundary does not occur. 

Clipboard: The holding place for the material the 
user last cut or copied; a buffer area in memory. 
Information on the Clipboard can be inserted 
(pasted) into documents. In memory, the 
contents of the clipboard are called the desk 
scrap, 

clipping region: The region to which an 
application limits drawing in a GrafPort. 

clock: (1) The timing circuit that controls 
execution of a microprocessor. Also called system 
clock, (2) An integrated circuit, often with battery- 
backup memory, that gives the current date and 
time. 
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close box; The small white box on the left side of 
the title bar of an active window. Clicking it doses 
the window. 

color table: One table of 16 lookup tables in 
Apple nos memory. The table lists the available 
color values for a scan line. 

compaction: The rearrangement of allocated 
blocks in memory to open up larger contiguous 
areas of free space. 

compiler: A program that produces object files 
(containing machine-language code) from source 
files written in a high-level language such as C. 
Compare assembler. 

content region: The area in a window in which 
your application presents information to the user. 

control: An object in a window with which the 
user, using the mouse, can cause instant action 
with visible results or change settings to modify a 
future action. 

control definition procedure: A procedure 
used to define the appearance and behavior of a 
custom control. 

Control Manager: The Apple IIGS tool set that 
manages controls, which are objects on the screen 
that the user can manipulate with the mouse to 
cause instant action or change settings. 

Control Panel: A desk accessory that lets the user 
change certain system parameters, such as speaker 
volume, display colors, and configuration of slots 
and ports. 

control record: A data structure that defines the 
appearance and behavior of a control. 

coordinate plane: A two-dimensional grid 
defined by QuickDraw n. All drawing commands 
are located in terms of coordinates on the grid. 

coordinates: X and Y locations on the 
QuickDraw II coordinate plane. Most QuickDraw n 
routines accept and return coordinates in the 
order (Y,X). 


copy: To duplicate something by selecting it and 
choosing Copy from the Edit menu. A copy of the 
selected portion is placed on the Clipboard, 
without affecting the original selection. 

C string: An ASCII character string terminated 
by a null character (ASCII value = 0). Compare 

Pascal string. 

C-type string: Same as C string. 

current font: The font currently being used by 
QuickDraw n to draw text. 

cursor: A symbol displayed on the screen, 
marking where the user’s next action will take effect 
or where the next character typed from the 
keyboard will appear. 

cursor record: The data structure that defines 
the height and width of the cursor, the image of the 
cursor, the mask controlling the appearance of the 
cursor, and the hot spot defining where the image 
of the cursor will be placed by the mouse. 

cut: To remove something by selecting it and 
choosing Cut from the Edit menu. The cut portion 
is placed on the Clipboard. 

data area: The name for a document as viewed in 
a window. The data area is the entire document, 
only a portion of which (the visible region) may be 
seen in the window at any one time. 

data bank register: A register in the 65C816 
processor that contains the high-order byte of the 
24-bit address that references data in memory. 

data structure: A specifically formatted item of 
data or a form into which data may be placed. 

DB register: See data bank register. 

dead character: A character with a character 
width of 0. 

default button: The button in a dialog box whose 
action will be executed if the user presses the 
Return key. 
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default prefix: The pathname prefix attached by 
ProDOS l6 to a partial pathname when no prefix 
number is supplied by the^application. The default 
prefix is equivalent to prefix number 0/. 

dereference: To substitute a pointer for a 
memory handle, or a value for a pointer. When 
you dereference a memory block’s handle, you 
access the block directly (through its master 
pointer) rather than indirectly (through its 
handle). 

descender: Any part of a character that lies 
below the base line. 

descent: In a font, the distance between the base 
line and the descent line. 

descent line: A horizontal line that coincides 
with the bottoms of character descenders (such as 
the tail on a lowercase “p”) that extends farthest 
below the base line. See also ascent line, base 
height, font height. 

desk accessory: A “mini-application” that is 
available to the user regardless of whether another 
application is running. The Apple IIGS supports 
two types of desk accessories: dassic desk 
accessories and new desk accessories. 

desk accessory event: An event that occurs 
whenever the user presses Control-Apple-Escape 
to invoke a dassic desk accessory. 

Desk Accessory menu: The menu whose title is 
a colored apple symbol. 

Desk Manager: The Apple IIGS tool set that 
executes desk accessories and enables applications 
to support them. 

desk scrap: A piece of data, maintained by the 
Scrap Manager, taken from one application and 
available for insertion into another. 

desktop: The visual interface between the 
computer and the user—the menu bar and the gray 
(or solid-colored) area on the screen. In many 
applications the user can have a number of 
documents on the desktop at the same time. 


desktop user interface: See desktop. 

destination location: The location (memory 
buffer or portion of the QuickDraw n coordinate 
plane) to which data such as text or graphics are 
copied. See also destination rectangle. 

destination rectangle: (1) The rectangle (on 
the QuickDraw n coordinate plane) in which text 
or graphics are drawn when transferred from 
somewhere else. Compare source rectangle. 

(2) In LineEdit, the rectangle that determines 
where the text will be drawn. 

device: A piece of hardware used in conjunction 
with a computer and under the computer’s 
control. Also called peripheral device because 
such equipment is often physically separate from, 
but attached to, the computer. 

device driver: A program that handles the 
transfer of data to and from a peripheral device, 
such as a printer or disk drive. 

device driver event: An event generated by a 
device driver. 

dial: An indicator on the screen that displays a 
quantitative setting or value. Usually found in 
analog form, such as a fuel gauge or a 
thermometer. A scroll bar is a standard type of 
dial. 

dialog: See dialog box. 

dialog box: A box on the screen that contains a 
message requesting more information from the 
user. See also alert box. 

Dialog Manager: The Apple IIGS tool set that 
manipulates dialog boxes and alerts, which appear 
on the screen when an application needs more 
information to carry out a command or when the 
user needs to be notified of an important situation. 

dialog pointer: A pointer to a dialog’s GrafPort; 
equivalent to the window pointer for the dialog 
box. 

dialog record: Information describing a dialog 
window that is maintained by the Dialog Manager. 
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dialog template: A record that contains 
information about a dialog to be created. 

dialog window: The window in which a dialog 
box appears. 

digital oscillator chip (DOC): An integrated 
circuit in the Apple IIGS that contains 32 digital 
oscillators, each of which can generate a sound 
from stored digital waveform data. 

dim: On the Apple IIGS desktop, to display a 
control or menu item in gray rather than black, to 
notify the user that the item is inactive. 

direct page: A page (256 bytes) of bank $00 of 
Apple IIGS memory, any part of which can be 
addressed with a short (1-byte) address because its 
high-order address byte is always $00 and its 
middle address byte is the value of the 65C816 
direct register. Co-resident programs or routines 
can have their own direct pages at different 
locations. The direct page corresponds to the 6502 
processor’s zero page. The term direct page is 
often used informally to refer to any part of the 
direct-page/stack space. Compare zero page. 

dlrect-page/stack segment: A program 
segment that is used to initialize the size and 
contents of an application’s stack and direct page. 

direct-page/stack space: A single block of 
memory that contains an application’s stack and 
direct page. 

direct register: A hardware register in the 
65C816 processor that specifies the start of the 
direct page. 

disable: To make unresponsive to user actions. A 
dialog box control that is disabled does nothing 
^en selected or manipulated by the user. In 
appearance, however, it is identical to an enabled 
control. Compare Inactive. 

disabled menu: A menu that can be pulled 
down, but in which items are dimmed and not 
selectable. 


display mode: A specification for the way in 
which a video display functions, including such 
parameters as text or graphics display, available 
colors, and number of pixels. The Apple IIGS has 
two text display modes (40 column and 80 
column), two standard Apple II graphics display 
modes 020 mode and 640 mode), and two new 
Super Hi-Res graphics display modes. 

display rectangle: A rectangle that determines 
where an item is displayed within a dialog box. 

dispose: To permanentiy deallocate (a memory 
block). The Memory Manager disposes of a 
memory block by removing its master pointer. 
Any handle to that pointer will then be invalid. 
Compare purge. 

dithering: A technique for alternating the values 
of adjacent pixels to create the optical effect of 
intermediate values. Dithering can give the effect 
of shades of gray on a black-and-white display, or 
more colors on a color display. 

dividing line: A line that divides groups of items 
in a menu; such a line uses the space of an entire 
item and requires an item record. Compare 

underline. 

DOO See digital oscillator chip. 

document: A file created by an application. 

document window: A window that displays a 
document. One of the two predefined window 
formats. Compare alert window. 

double-click: To position the pointer where you 
want an action to take place, and then press and 
release the mouse buuon twice in quick succession 
without moving the mouse. 

draft printing: The print method that the 
LaserWriter uses. QuickDraw n calls are converted 
directiy into command codes the printer 
understands, which are then immediately used to 
drive the printer. Compare spool printing. 
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drag: To position the pointer on something, 
press and hold the mouse button, move the 
mouse, and release the mouse button. When you 
release the mouse button, you either confirm a 
menu selection or move an object to a new 
location. 

drag region: A region in a window (usually on 
the title bar) in which the mouse pointer must be 
placed before the user can drag the window. 

draw: In QuickDraw II, to color pixels in a pixel 
image. 

drawing environment: The complete 
description of how and where drawing may take 
place. Every open window on the Apple IIGS 
screen is associated with a GrafPort record, which 
specifies the window*s drawing environment 
Same as graphic port, port. 

drawing mask: An 8-bit by 8-bit pattern that 
controls which pixels in the QuickDraw II pen will 
be modified when the pen draws. 

drawing mode: One of l6 possible interactions 
between pixels in QuickDraw IPs pen pattern and 
pixels already on the screen that fall under the 
pen’s path. In modeCopy mode, for example, 
pixels already on the screen are ignored. In 
modeXOR mode, on the other hand, bits in pixels 
on the screen are XOR’d with bits in pixels in the 
pen; the resulting pixels are drawn on the screen. 
See also pen mode, text mode. 

drawing pen; See pen. 

driver: See device driver. 

dynamic segment: A load segment capable of 
being loaded during program execution. 
Compare static segment 

edit record: A complete text-editing 
environment in the LineEdit Tool Set, which 
includes the text to be edited, the GrafPort and 
rectangle in which to display the text, the 
arrangement of the text within the rectangle, and 
other editing and display information. 


e flag: One of three flag bits in the 65C816 
processor that programs use to control the 
processor’s operating modes. The setting of the 
e flag determines whether the processor is in 
native mode (6502) or emulation mode (65816). 
See also m flag, x flag. 

empty handle: A handle pointing to a NIL 
master pointer. 

emulate: To operate in a way identical to a 
different system. For example, the 65C816 
microprocessor in the Apple IIGS can carry out all 
the instructions in a program originally written for 
an Apple n that uses a 6502 microprocessor, thus 
emulating the 6502. 

emulation mode: The 8-bit configuration of the 
65C816 processor in which it functions like a 6502 
processor in all respects except clock speed. 

enable: To make responsive to user 
manipulation. A dialog or menu that is enabled 
can selected by the user. Enabling does not 
affect how an item is displayed. Compare 

activate. 

end-of-flle: See EOF. 

EOF (end-of-fUe): The logical size of a ProDOS 
l6 file; it is the number of bytes that may be read 
from or written to the file. 

erasing: In QuickDraw 11, to color an area with 
the background pattern. 

error: The state of a computer after it has 
detected a fault in one or more commands sent to 
it. Also called error condition. 

error condition; See error. 

error message: A message issued by the system 
or application program when it has encountered 
an abnormal situation or an error in data. 

event: A notification to an application of some 
occurrence (such as an intermpt generated by a 
keypress) that the application may want to respond 
to. 
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event code: A numeric value assigned to each 
event by the Event Manager. Compare task code. 

event-driven program: A program that 
responds to user inputs in red time by repeatedly 
testing for events. An event-driven program does 
nothing until it detects an event such as a click of 
the mouse button. 

Event Manager: The Apple IIGS tool set that 
detects events as they happen and passes the 
events to the application or appropriate event 
handler, such as TaskMaster or GetNextEvent. 

event mask: A parameter passed to an Event 
Manager routine to specify which types of events 
the routine should apply to. 

event message: A field in the event record that 
contains additional information about the event. 

event queue: A list of pending events 
maintained by the Event Manager. 

event record: The internal representation of an 
event, through which your program learns all 
pertinent information about that event. 

event type: The type of event reported to the 
Event Manager. 

execution environment: See operating 
environment. 

execution mode: One of two general states of 
execution of the 65C816 processor: native mode 
and 6502 emulation mode. 

expansion slot: See slot. 

Extended value: An 80-bit signed floating-point 
value with 64 bits of fraction. 

extended task event record: A data structure 
based on the event record that contains 
information used and returned by TaskMaster. 

FALSE: Zero. The result of a Boolean operation. 
The opposite of TRUE. 


family name: The name identifying a font 
family. For example, the font family named 
Helvetica includes 10-point Helvetica, 12-point 
Helvetica Bold, and 36-point Helvetica 
Underlined. See also font family. 

family number: The number identifying a font 
family. There is a one-to-one correspondence 
between family number and family name; that is, 
any two fonts with the same family number should 
have the same family name. 

FamSpecBlts: A bit flag in the Font Manager that 
restricts the range of font families available to a 
calling routine. 

FamStatBlts: A bit flag in the Font Manager that 
reports on the status of a font family. 

file: Any named, ordered collection of 
information stored on a disk. Application 
programs and operating systems on disks are 
examples of files; so also are text or graphics 
materials created by applications and saved on 
disks. Text and graphics files are also called 
documents. 

filename: The string of characters that identifies 
a particular file within its directory. ProDOS 
filenames may be up to 15 characters long. 
Compare pathname. 

file type: An attribute of a ProDOS file that 
characterizes its contents and indicates how the 
file may be used. On disk, file types are stored as 
numbers; in a directory listing, Aey are often 
displayed as three-character or single-word 
mnemonic codes. Compare auxiliary type. 

filling: In QuickDraw n, using a specified pattern 
and the drawing mask to fill the interior of a shape. 

fill mode: A display option in Super Hi-Res 320 
mode. In fill mode, pixels in memory with the 
value 0 are automatically assigned the color of the 
previous nonzero pixel on the scan line; the 
program thus need assign explicit pixel values only 
to change pixel colors. 
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filter procedtire: A procedure that allows the 
application programmer to control the types of 
events handled by the Dialog Manager. 

firmware: Programs stored permanently in 
ROM; most provide an interface to system 
hardware. Such programs (for example, the 
Monitor program) are built into the computer at 
the factory. They can be executed at any time but 
cannot be modified or erased. Compare 
hardware, software. 

fixed: Not movable in memory once allocated. 
Program segments that must not be moved are 
placed in fixed memory blocks. Also called 
immovable. The opposite of movable. 

fixed address: A memory block that must be at a 
specified address when allocated. 

fixed bank: A block of memory that must start in 
a specified bank. 

Fixed value: A 32-bit signed value with l6 bits of 
fraction. 

flag: A variable whose value (usually 1 or 0, 
standing for TRUE or FALSE) indicates whether 
some condition holds or whether some event has 
occurred. A flag is used to control the program’s 
actions at some later time. 

folden The visual representation of a 
subdirectory. See also subdirectory. 

font: In typography, a complete set of type in 
one si 2 e and style of character. In computer usage, 
a collection of letters, numbers, punctuation 
marks, and other typographical symbols with a 
consistent appearance; the size and style can be 
changed readily. See also font scaling. 

font bounds rectangle: The smallest rectangle 
that would enclose all the pixels of every character 
in a font; that is, the rectangle that is the union of 
all the character bounds rectangles of the 
characters in the font. 


font family: All fonts that share the same name 
but may vary in size or style. For example, all fonts 
named Helvetica are iii the same family, even 
though that family contains Helvetica, Helvetica 
Narrow, and Helvetica Bold. 

font beigbt: The vertical distance from a font’s 
ascent line to its descent line. 

font ID: A number that specifies a font by family, 
style, and size. 

font ID record: A record containing the number 
that specifies a font by fjimily, style, and size. 

Font Manager: The Apple IIGS tool set that 
allows applications to use different fonts. 

font rectangle: The smallest rectangle that 
would completely enclose all the foreground 
pixels of the charaaers of a font if the characters 
were drawn so that their character origins 
coincided. 

font scaling: A process by which the Font 
Manager creates a font at one size by enlarging or 
reducing characters in an existing font of another 
size. 

font size: The size of a font in points, from 1 to 
255. The Font Manager defines the font size as a 
byte; QuickDraw II and the Apple IIGS font record 
define the font size as a word. 

FontSpecBlts: A bit flag in the Font Manager that 
restricts the range of fonts available to a calling 
routine. 

FontStatBlts: A bit flag in the Font Manager that 
reports on the status of a font. 

font strike: A 1-bit-per-pixel pixel image 
consisting of the character images of every defined 
character in the font, placed sequentially in order 
of increasing ASCII code. 

font style: The style in which a font was 
designed. The Font Manager defines the style style 
as a byte; QuickDraw II and the Apple IIGS font 
record define the font style as a word. 
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font substitution: An option in the LaserWriter 
style dialog box in the Print Manager, font 
substitution tells the system to substitute one font 
for another if the specified font is not available on 
the LaserWriter. 

foreground color: The color of the foreground 
pixels in text; by default it is white. 

foreground pixels: In a character image, the 
pixels corresponding to the character itself; that 
is, the bits set to 1 in the image. 

FPT: See function pointer table. 

Frac value: A 32-bit signed value with 30 bits of 
fraction. 

fragmentation: A condition in which free 
(unallocated) portions of memory are scattered 
due to repeated allocation and deallocation of 
blocks by the Memory Manager. 

frame region: The part of a window that 
surrounds the window's content region and 
contains standard window controls. 

framing: In QuickDraw II, using the current pen 
size, pen pattern, drawing mask, and pen mode to 
draw an outline of a shape. 

full native mode: See native mode. 

full pathname: The complete name by which a 
file is specified, starting with the volume directory 
name. A full pathname always begins with a slash 
( /) because a volume directory name always 
begins with a slash. See also pathname. 

function pointer table (FPT): A table, 
maintained by the Tool Locator, that points to all 
routines in a given tool set. 

GCB: See generator control block. 

general logic unit: See GLU. 

generator: In the swap mode of the DOC, a 
functional unit formed from a pair of oscillators. 


generator control block (GCB): A l6-byte 
block in the sound routines' work area that controls 
one generator. 

GetNextEvent: The Event Manager call that an 
application can make on each cycle through its 
main event loop. Compare TaskMaster. 

global coordinates: The coordinate system 
assigned to a pixel image (such as screen memory) 
that QuickDraw II draws to. In global coordinates, 
the boundary rectangle's origin (top left corner) 
has the value (0,0). Compare local coordinates. 

GLU (general logic unit): A class of custom 
integrated circuits used as interfaces between 
different parts of the computer. 

go-away region: A region in a window frame, 
corresponding to the close box. Clicking inside 
this region of the active window makes the window 
close or disappear. 

GrafPort: A data structure (record) that specifies 
a complete drawing environment, including such 
elements as a pixel image, boundaries within 
which to draw, a character font, patterns for 
drawing and erasing, and other pen 
characteristics. 

graphic port: A specification for how and where 
(QuickDraw n draws. A graphic port is defined by 
its GrafPort record; an application may have more 
that one graphic port open at one time, each 
defined by its own GrafPort. Same as drawing 
environment, 

grow image: A dotted outline of an entire 
window plus the lines delimiting the title bar, size 
box, and scroll bar areas. The image can be pulled 
around to follow the movements of the mouse until 
the mouse button is released. 

grow region: A window region in which dragging 
changes the size of the window. 

handle: See memory handle. 
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hardware: In computer terminology, the 
machinery that makes up a computer system. 
Compare flrmware, software. 

Heartbeat routines: Routines that execute at the 
heartbeat interrupt signal, during the vertical 
blanking interval (every l/60 of a second). 

hex: See hexadecimal 

hexadecimal, hex: The representation of 
numbers in the base-16 system, using the ten digits 
0 through 9 and the six letters A through F. Each 
hexadecimal digit corresponds to a sequence of 
four binary digits, or bits. Hexadecimal numbers 
are lasually preceded by a dollar sign ($). 

hide: To make invisible on the screen (but not 
necessarily to discard). 

highlight: To make something visually distinct. 
For example, when a button on a dialog box is 
selected, it appears as light letters on a dark 
background, rather than dark on light. An active 
window or control is highlighted differently than 
an inactive one. 

horizontal blanking: The interval between the 
drawing of each scan line on a video display. 

hot spot: The interval between the drawing of 
each scan line on a video display. 

Human Interface Guidelines: Apple 
Computer’s set of conventions and suggestions for 
writing desktop programs. Programs that follow 
the Human Interface Guidelines: The Apple 
Desktop Interface present a consistent and 
friendly interface to users. 

Icon: An image that graphically represents an 
object, a concept, or a message. 

1 flag: A bit in the 65C816 microprocessor’s 
Processor Status register that disables interrupts if 
set to 1. 

Image: A representation of the contents of 
memory. A code image consists of machine- 
language instructions or data that may be loaded 
unchanged into memory. See also pixel Image. 


Image pointer: In QuickDraw II, the pointer to 
the first byte of a pixel image. 

Image width: (1) Part of the QuickDraw n 
locinfo record that specifies the width of each line 
of a pixel image; the width must be an even 
multiple of 8 bytes. (2) For characters, same as 
character image xvidth. 

Immovable: See fixed. 

Inactive: Said of controls that have no meaning 
or effect in the current context, such as an Open 
button when no document has been selected to be 
opened. These inactive controls are not affected 
by the user’s mouse action and are dimmed on the 
screen. Compare disable. 

Index register: A register in a computer 
processor that holds an index for use in indexed 
addressing. The 6502 and 65C816 
microprocessors used in the Apple II family of 
computers have two index registers, called the 
X register and the Y register. 

Indicator: On a dial type of control, the moving 
part that displays the current setting. 

Information bar: An optional component of a 
window. If present, the information bar appears 
just below the tide bar. It may contain any 
application-defined information. 

Initialization segment: A segment in an irutial 
load file that is loaded and executed 
independentiy of the rest of the program. It is 
commonly executed first, to perform any 
inidalization that the program may require. 

input/output: See I/O. 

Insertion point: The place in a document where 
something will be added; it is selected by clicking 
and is normally represented by a blinking vertical 
bar. 

Integer value: A l6-bit signed or unsigned 
value. 

Integer Math String: An ASCII string with no 
length indicadon supplied by the string itself. 
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Integer Math Tool Set: The Apple IIGS tool set 
that performs simple mathematical functions on 
integers and other fixed-point numbers and 
converts numbers to their ASCII string- 
equivalents. 

interface library: A set of variable- and data- 
structure definitions that link a program (such as a 
C application) with software written in another 
language (such as the Apple IIGS Toolbox). 

interrupt: A temporary suspension in the 
execution of a main program that allows the 
computer to perform some other task, typically in 
response to a signal from a peripheral device or 
other source external to the computer. 

interrupt environment: The machine state, 
including register length and contents, that the 
interrupt handler executes within. 

interrupt mode: A mode in which interrupts are 
used to synchronize drawing with vertical 
blanking. 

inverting: In QuickDraw II, using the drawing 
mask to invert the pixels in the interior of a shape. 

I/O (input/output): A general term that 
encompasses input/output activity, the devices 
that accomplish it, and the data involved. 

I/O space: The portion of the memory map in a 
standard Apple II (and in banks $E0 and $E1 of an 
Apple IIGS) with addresses between $0000 and 
$CFFF. Programs perform VO by writing to or 
reading from locations in this I/O space. 

item: A component of a dialog box, such as a 
button, a text field, or an icon. 

item descriptor: In a dialog box, a pointer or a 
handle to additional information concerning a 
dialog item. 

item ID: A unique number that defines an item 
in a dialog box and allows further reference to it. 

item line: The line of text that defines a menu 
item’s name and appearance. 


item list; A list of information about all the items 
in a dialog box or an alert box. 

item template: A record that contains 
information about the items in a dialog box. 

item type: Identifies the type of dialog item, 
usually represented by a predefined constant (such 
as statText) or a series of constants. 

item value: In a dialog box, additional 
information concerning a dialog item. 

Job dialog box: A dialog box presented when the 
user selects Print from the File menu. 

Job subrecord: A field in the print record that 
contains information about a particular printing 
job. See also print record. 

Journaling mechanism: A mechanism that can 
separate the Event Manager from the user and feed 
the manager events from a file. 

JSL (Jump to Subroutine Long): A 65816 
assembly-language instruction that requires a long 
0-byte) address. JSL can be used to transfer 
execution to code in another memory bank. 

JSR Oump to Subroutine): A 6502 and 65816 
assembly-language instruction that requires a 
2-byte address. 

Jump Table: (1) A table constructed in memory 
by the System Loader from all Jump Table 
segments encountered during a load. The Jump 
Table contains all references to dynamic segments 
that may be called during execution of the 
program. (2) The mechanism the Sound Tool Set 
uses to find a low-level sound routine. 

Jump Table segment: A segment in a load file 
that contains all references to dynamic segments 
that may be called during execution of that load 
file. The Jump Table segment is created by the 
linker. In memory, the loader combines all Jump 
Table segments it encounters into the Jump Table. 
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K: See kilobyte. 

kemlng; The situation that occurs when a 
character has foreground pixels to the left of the 
old pen position or to the right of the new pen 
position or both. When kerning occurs, the 
character images of adjacent characters may 
overlap. 

keyboard equivalent: The combination of the 
Apple key and another key, used to invoke a menu 
item from the keyboard. 

key-down event: An event type caused by the 
user pressing any character key on the keyboard or 
keypad. The character keys include all keys except 
Shift, Caps Lock, Control, Option, and Apple, 
which are called modifier keys. Modifier keys are 
treated differendy and generate no keyboard 
events of their own. 

kilobyte (K): A unit of measurement consisting 
of 1024 (2^^ bytes. In this usage, kilo (from the 
Greek, meaning a thousand) stands for 1024. Thus, 
64K memory equals 65,536 bytes. See also 

megabyte. 

landscape mode: A printing mode in which text 
is printed top to bottom (that is, longways) on the 
paper, 

leading: Pronounced “LED-ing.” The space 
between lines of text. It is the number of pixels 
verdcally between the descent line of one 
character and the ascent line of the character 
immediately beneath it. 

leftward kem: For characters, the distance in 
pixels from the character origin to the left edge of 
the character. 

length byte: The first byte of a Pascal string. It 
specifies the length of the string, in bytes. 

library, library file: An object file containing 
program segments, each of which can be used in 
any number of programs. The linker can search 
through the library file for segments that have 
been referenced in the program source file. 


library file: See library. 

limit rectangle: The rectangle that limits the 
travel of a region that is being dragged with the 
mouse. 

line: In QuickDraw II, an infinitely thin graphic 
object that is represented by its ends, which are 
defined by two points. 

lineEdlt Tool Set: The Apple IIGS tool set that 
provides simple text-edidng funcdons. It is used 
mostly in dialog boxes. 

line height: The t<j)tal amount of vertical space 
from line t6 line in a text document. Line height is 
the sum of ascent, descent, and leading. 

list: As defined by the List Manager, a scrollable, 
vertical arrangement of similar items on the 
screen; the items are selectable by the user. 

list control: A custom control created by the List 
Manager. 

list control record: A data structure that defines 
the appearance of a list control after the control 
has been created. 

list record: A data structure that defines the 
initial appearance of a list control. 

List Manager: The Apple IIGS Tool set that allows 
an application to present the user with a list from 
which to choose (for example, the Font Manager 
uses the List Manager to arrange lists of fonts). 

local coordinates: A coordinate system unique 
to each GrafPort and independent of the global 
coordinates of the pixel image that the port is 
associated with. For example, local coordinates 
do not change as a window is dragged across the 
screen; global coordinates do not change as a 
window’s contents are scrolled. 

location table: In a font, an array of integers with 
an entry for each character code. 

locinfo: Acronym for location information. The 
data structure (record) that ties the coordinate 
plane to an indvidual pbcel image in memory. 
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lock: To prevent a memory block from being 
moved or purged. A block may be locked or 
unlocked by a call to the Memory Manager. 
Compare unlock. 

long, long word: On the Apple IIGS, a 32-bit 
(4-byte) data type. 

Longlnt value: A 32-bit signed or unsigned 
value. 

Macintosh: A family of Apple computers; for 
example, the Macintosh 512K and the Macintosh 
Plus. Macintosh computers have high-resolution 
screens and use mouse devices for choosing 
commands and for drawing pictures. 

macro: A single keystroke or command that a 
program replaces with several keystrokes or 
commands. For example, the APW Editor allows 
you to define macros that execute several editor 
keystroke commands; the APW Assembler allows 
you to define macros that execute instructions and 
directives. Macros are almost like higher-level 
language instructions, making assembly-language 
programs easier to write and complex keystrokes 
easier to execute. 

macro library; A file of related macros. 

main event loop: The central routine of an 
event-driven program. During execution, the 
program continually cycles through the main 
event loop, branching off to handle events as they 
occur and then returning to the event loop. 

mainlD: A subfield of the user ID. Each running 
program is assigned a unique mainlD field. 

manager: See tool set. 

mask: A parameter, typically one or more bytes 
long, whose individual bits are used to set or block 
particular features. See, for example, event 
mask. 

master color value: A 2-byte number that 
specifies the relative intensities of the red, green, 
and blue signals output by the Apple IIGS video 
hardware. 


master pointer: A fixed location that always 
contains the address of a specified block, 
regardless of whether the block is moved See also 

memory handle. 

master user ID: The value of a user ID 
disregarding the contents of the auxK> field. If an 
application allocates various memory blocks and 
assigns them unique IDs consisting of auxID 
values added to its own user ID, then all will share 
the same master user ID and all can be purged or 
disposed with a single call. 

Mb: See megabyte. 

megabyte (Mb): A unit of computer memory or 
disk drive capacity equaling 1,048,576 bytes. 

megahertz (MHz): A unit of measurement of 
frequency, equal to 1,000,000 hertz (cycles per 
second). 

memory attributes word: A word that 
determines how a specified memory block is 
allocated and maintained. 

memory block: See block (2). 

memory expansion card: A memory card that 
increases Apple IIGS internal memory capacity 
beyond 256K, up to 8 megabytes 

memory fragmentation: See fragmentation. 

memory handle: A number that identifies a 
memory block. A handle is a pointer to a pointer; 
it is the address of a master pointer, which in turn 
contains the address of the block. Also called 
simply handle. 

Memory Manager: The Apple IIGS Tool set that 
manages memory use. The Memory Manager 
keeps track of how much memory is available and 
allocates memory blocks to hold program 
segments or data. 

menu: A list of choices presented by a program, 
from which the user can select an action. See also 

pull-down menu. 
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menu bar: The horizontal strip at the top of the 
screen that contains menu titles for the pull-down 
menus. 

menu bar record: A data structure that contains 
the menu position, color, menu lists, item lists, 
and other flags the Menu Manager needs to 
manage menus. 

menu definition procedure: A procedure used 
to define the appearance and behavior of a custom 
menu. 

menu ID: A number in the menu record that 
identifies an individual menu. 

menu item: On a menu, the text of a command 
or a line dividing groups of choices. 

menu line: A line of text plias code characters 
that defines the appearance of a particular menu 
title. 

Menu Manager: The Apple IIGS Tool Set that 
maintains the pull-down menus and the items in 
the menus. 

menu record: A data structure that provides 
information about one of the menus in a menu 
bar. 

m flag; One of three flags in the 65816 
microprocessor's Processor Status register that 
controls execution mode. When the m flag is set to 
1, the accumulator is 8 bits wide; otherwise, it is l6 
bits wide. See also e flag, x flag. 

MHz: See megahertz. 

microprocessor: A central processing unit that 
is contained in a single integrated circuit. The 
Apple IIGS uses a 65C816 microprocessor. 

minimum blink intervaL The minimum time 
between blinks of the caret 

minimum version number: The minimum 
version of a particular tool set that an application 
needs to function. 


minipalette: In Super Hi-Res 640 mode, a 
quarter of the color table. Each pixel in 640 mode 
can have one of four colors specified in a 
minipalette. 

Miscellaneous Tool Set: The Apple IIGS tool set 
that includes mostly system-level routines that 
must be available for other tool sets. 

missing character: In a font, a character that 
does not have a defined symbol. 

missing symbol: In a font, the symbol 
substituted for any ASCII value for which the font 
does not have a defined symbol. In the Apple IIGS 
system font, the missing symbol is a box 
containing a question mark. 

modal dialog box: A dialog box that puts the 
machine in a state where the user cannot execute 
functions outside of the dialog box until the dialog 
box is closed. Compare modeless dialog box. 

mode: A state of a computer or system that 
determines its behavior. A manner of operating. 

modeless dialog box: A dialog box that does 
not require the user to respond before doing 
anything else. Unlike a modal dialog box, it is 
possible to keep working even if the box is still in 
use. Compare modal dialog box. 

modifier keys: The Shift, Caps Lock, Control, 
Option, and Apple keys. Such keys do not generate 
a keyboard event by themselves; rather, their 
states are recorded whenever another event is 
posted. 

monospaced: Said of a font whose charaaer 
widths are all identical. Compare proportionally 
spaced. 

mouse: A small device the user moves around on 
a flat surface next to the computer. The mouse 
controls a pointer on the screen whose 
movements correspond to those of the mouse. 

The pointer selects operations, moves data, and 
draws graphic objects. 
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mouse button: A button on a mouse device with 
which the user selects objects on the saeen. 

mouse clamps: Values that establish the 
minimum and maximum X and Y coordinates for 
the mouse. 

mouse-down: An action or an event, signifying 
that the user has pressed the mouse button. 

mouse-up: An action or an event, signify^ing that 
the user has released the mouse button. 

movable: Able to be moved to different memory 
locations during program execution (a memory 
block attribute). The opposite of fixed. 

native mode: The l6-bit operating configuration 
of the 65C816 microprocessor. 

NDA: See new desk accessory* 

new desk accessory (NDA): A desk accessory 
designed .to execute in a desktop, event-driven 
environment. Compare classic desk accessory* 

NIL: A value of 0. A pointer is NIL if its value is all 
zeros. A memory handle is NIL if the address it 
points to is filled with zeros. Handles to purged 
memory blocks are NIL. 

nonspeclal, normal memory: Memory that 
has no special restrictions on it. On the 
Apple IIGS, such memory includes banks $2-$DF 
and parts of banks $E0 and $E1. 

Note Sequencer: The Apple IIGS tool set that 
makes it possible to play music asynchronously in 
programs. 

Note Synthesizer: An Apple IIGS tool set that 
facilitates aeation and manipulation of musical 
notes. 

null event: An event reported when there are no 
other events to report. 

object module format (OMF): The file format 
used in Apple IIGS object files, library files, and 
load files. Compare text file format. 


offset: The number of character positions or 
memory locations away from a point of reference. 

OK: One of two predefined item ID numbers for 
dialog box buttons (OK = 1). Compare Cancel 

OMF; See object module format* 

operating environment: The overall hardware 
and software setting within which a program runs. 
Also called execution environment. 

operating system: A general-purpose program 
that organizes the actions of the various parts of 
the computer and its peripheral devices. See also 

disk operating system. 

origin: (1) The first memory address of a 
program or of a portion of one. The first 
instruction to be executed. (2) The location (0,0) 
on the QuickDraw II coordinate plane, in either 
global coordinates or local coordinates. (3) The 
top left corner of any rectangle (such as a 
boundary rectangle or a port rectangle) in 
QuickDraw II. (^ See character origin* 

oscillator: A device that generates a vibration. In 
the Apple IIGS digital oscillator chip, an oscillator 
is an address generator that points to the next data 
byte in memory that represents part of a particular 
sound wave. 

oval: A circle or an ellipse, one of the 
fundamental classes of objects drawn by 
QuickDraw H. 

pack: To compress data into a smaller space to 
conserve storage space. 

page: (1) A portion of memory 256 bytes long 
and beginning at an address that is an even 
multiple of 256. Memory blocks whose starting 
addresses are an even multiple of 256 are said to be 
page aligned. (2) An area of main memory 
containing text or graphic information being 
displayed on the screen. 

page-aligned: Said of a memory block that starts 
at a memory address that is an even multiple of 256 
(a memory block attribute). See also page (1). 
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paging region: In a scroll bar, the area a user 
clicks to move the view of the data a page at a time. 

painting: In QuickDraw II, using the current pen 
pattern, drawing mask, and pen mode to fill the 
interior of a shape. 

palette: The full set of colors available for an 
individual screen pixel. 

parameter: A value passed to or from a function 
or other routine. 

parameter RAM: RAM on the Apple IIGS clock 
chip. A battery preserves the clock settings and the 
RAM contents when the power is off. Control 
Panel settings are kept in battery RAM. 

part code: A number between 1 and 255 that 
stands for a particular part of a control. The 
Control Manager uses part codes to allow different 
parts of a control to respond in different ways. 

partial pathname: A pathname that includes the 
filename of the desired file but excludes the 
volume directory name (and possibly one or more 
of the subdirectories in the path). It is the part of a 
pathname following a prefix; a prefix and a partial 
pathname together constitute a full pathname. A 
partial pathname does not begin with a slash 
because it has no volume directory name. 

PascaL A high-level programming language. 
Named for the philosopher and mathematician 
Blaise Pascal. 

Pascal string: An ASCII character string 
preceded by a single byte whose numerical value is 
the number of characters in the string. Compare 
C string. 

Pascal-type string: Same as Pascal string. 

paste: To place the desk scrap (contents of the 
Clipboard—^whatever was last cut or copied) at the 
insertion point. 


pathname: A name that specifies a file. It is a 
sequence of one or more filenames separated by 
slashes, tracing the path through subdirectories 
that a program must follow to locate the file. See 
also hill pathname, partial pathname, prefix. 

pathname prefix: See prefix. 

pattern: An 8-by*8 pixel image, used to define a 
repeating design (such as stripes) or color. 

PB register: See program bank register. 

PC register: A register within the 65816 
microprocessor that keeps track of the memory 
address of the next instruction to be executed. PC 
stands for program counter 

pen: The conceptual tool with which QuickDraw II 
draws shapes and characters. Each GrafPort has its 
own pen. 

pen location: The position (on the coordinate 
plane) at which the next character or line will be 
drawn. 

pen mode: One of several Boolean operations 
that determine how the pen pattern is to affea an 
existing image. Compare text mode* 

pen pattern: See pattern. 

pen size: The size of the rectangle that will be 
used as the drawing pen. 

peripheral card: A hardware device placed 
inside a computer and connected to one of the 
computer’s peripheral expansion slots. Peripheral 
cards perform a variety of functions, from 
controlling a disk drive to providing a 
clock/calendar. 

peripheral device: See device. 

picture: A saved sequence of QuickDraw II 
drawing commands (and, optionally, picture 
comments) that you can play back later with a 
single procedure call; also, the image resulting 
from these commands. 
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pinning: The process of assigning positive 
overflows to the largest positive representable 
value and negative overflows to the largest negative 
representable value, 

pixel: A contraction of picture element, the 
smallest dot you can draw on the screen. Also a 
location in video memory that corresponds to a 
point on the graphics screen when the viewing 
window includes that location. In the Super Hi-Res 
display on the Apple IIGS, each pixel is 
represented by either 2 or 4 bits. See also pixel 
image. 

pixel image: A graphics image picture consisting 
of a rectangular grid of pixels. 

plain>styled: Said of a font or character that is 
not bold, italicized, underlined, or otherwise 
styled apart from ordinary text. 

plane: The front-to-back position of a window on 
the desktop. 

point: (1) A unit of measurement for type; 12 
points equal 1 pica, and 6 picas equal 1 inch; thus, 
1 point equals 1/72 inch. (2) A relative measure 
(taken from the type measure) used to distinguish 
font size on output devices. (3) In QuickDraw II, 
the Y and X coordinates of a location on the 
coordinate plane. 

pointer: An item of information consisting of the 
memory address of some other item. For 
example, the 65C816 stack register contains a 
pointer to the top of the stack. 

pointing device: Any device, such as a mouse, 
graphics tablet, or light pen, that can be used to 
specify locations on the computer screen. 

polygon: Any sequence of connected lines. 

port: (1) A socket on the back panel of the 
computer where the user can plug in a cable to 
connect a peripheral device, another computer, 
or a network. (2) A graphic port (GrafPort). 

portrait mode: A printing mode in which text 
prints from left to right on the paper. 


port rectangle: A rectangle that describes the 
active region of a GrafPort*s pbcel map—the part 
that QuickDraw II can draw into. The content 
region of a window on the desktop corresponds to 
the window’s port rectangle. 

portRect: The GrafPort field that defines the 
port’s port rectangle. 

post: To place an event in the event queue for 
later processing. 

prefix: A pathname starting with a volume name 
and ending with a subdirectory name. It is the part 
of a full pathname that precedes a partial 
pathname; a prefix and a partial pathname 
together constitute a full pathname. A prefix 
always starts with a slash (/) because a volume 
directory name always starts with a slash. 

prestyled: Said of a font that has a certain style 
or combination of styles built into the font’s 
design. 

printer information subrecord: A data 
structure within the print record that contains the 
information needed for page composition. 

printing loop: The page-by-page cycle that an 
application goes through when it prints a 
document. 

Print Manager: The Apple IIGS tool set that 
allows an application to use standard QuickDraw II 
routines to print text or graphics on a printer. 

print record: A record containing all the 
information needed by the Print Manager to 
perform a particular printing job. 

private scrap: A buffer (and its contents) set up 
by an application for cutting and pasting, 
analogous to but apart from the desk scrap. 

ProDOS: Acronym for Professional Disk 
Operating System, A family of disk operating 
systems developed for the Apple II family of 
computers. It includes ProDOS 8 and ProDOS 16. 
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ProDOS 8; A disk operating system developed 
for standard Apple II computers. It runs on 6502- 
series microprocessors and on the Apple IIGS 
when the 65C816 processor is in 6502 emulation 
mode. 

ProDOS 16: A disk operating system developed 
for 65C816 native-mode operation on the 
Apple IIGS. It is functionally similar to ProDOS 8 
but more powerful. 

program bank register: The 65C816 register 
whose contents form the high-order byte of all 
3-byte code address operands. Also called 
PB register, 

program counter: See PC register* 

program status register: A register in the 
65C816 microprocessor that contains flags 
reflecting the various aspects of machine state and 
operation results. 

proportionally spaced: Said of a font whose 
characters vary in width, so the amount of 
horizontal space needed for each character is 
proportional to its width. Compare 
monospaced. 

pseudo-type: A type that provides some 
additional information about a parameter of a 
toolbox routine. 

pull-down menu: A set of choices for actions 
that appears near the top of the display screen in a 
desktop application, usually overlaying the 
present contents of the screen without disrupting 
them. Dragging through the menu and releasing 
the mouse button while a command is highlighted 
chooses that command. 

purge: To temporarily deallocate a memory 
block. The Memory Manager purges a block by 
setting its master pointer to NIL (0). All handles to 
the pointer are still valid, so the block can be 
reconstructed quickly. Compare dispose. 


purge level: A memory block attribute, 
indicating that the Memory Manager may purge 
the block if it needs additional memory space. 
Purgeable blocks have different purge levels, or 
priorities for purging; these levels are set by 
Memory Manager calls. 

queue: A list in which entries are added (pushed) 
at one end and removed (pulled) at the other end, 
causing entries to be removed in first-in, first-out 
(FIFO) order. Compare stack. 

QuickDraw BE: The Apple IIGS tool set that 
controls the graphics environment and draws 
simple objects and text. Other tools call 
QuickDraw n to draw such things as windows. 

QuickDraw n Auxiliary: The Apple IIGS tool set 
that provides extensions to the capabilities of 
QuickDraw E. 

QuickDraw n Auxiliary icon record: A data 
structure that defines the appearance of an icon. 

quit: To terminate execution in an orderly 
manner. Apple IIGS applications quit by making a 
ProDOS l6 QUIT call or the equivalent. 

radio button: A common type of control in 
dialog boxes. Radio buttons are small circles 
organized into families; clicking any button on 
turns off all the others in the family, like the 
buttons on a car radio. See also check box. 

RAM: See random-access memory. 

random-access memory (RAM): Memory in 
which information can be referred to in an 
arbitrary or random order. Programs and other 
data in RAM are lost when the computer is turned 
off. Technically, the read-only memory (ROM) is 
also random access, and what’s called RAM 
should correctly be termed read-write memory. 
Compare read-only memory. 

range mode: In the List Manager, a selection 
mode that allows the user to select a range of 
members in a list 
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read-only memory (ROM): Memory whose 
contents can be read, but not changed; used for 
storing firmware. Information is placed into ROM 
once, during manufacture; it then remains there 
permanendy, even when the computer’s power is 
turned off. Compare random-access memory. 

real font: A font that exists on disk or was added 
by an application and marked as real Compare 

unreal font 

rectangle: One of the fundamental shapes drawn 
by QuickDraw II. Rectangles are completely 
defined by two points—their upper left and lower 
right corners on the coordinate plane. The upper 
left corner of any rectangle is its origin. 

reentrant: Said of a routine that is able to accept 
a call while one or more previous calls to it are 
pending, without invalidating the previous calls. 
Under certain conditions, the Apple IIGS 
Scheduler manages execution of roudnes that are 
not reentrant. 

region: An arbitrary area or set of areas on the 
QuickDraw II coordinate plane. The oudine of a 
region must be one or more closed loops. 

relocatable: Characteristic of a load segment or 
other program code that includes no references to 
specific address, and so can be loaded at any 
memory address. A relocatable segment consists 
of a code image followed by a relocadon 
dictionary. Compare absolute. 

relocation: The act of modifying a program in 
memory so that its address operands correcdy 
reflect its location and the locations of other 
segments in memory. Relocation is performed by 
the system loader when a relocatable segment is 
first loaded into memory. 

repeat delay: The time interval before the first 
auto-key event is generated. 

repeat speed: The time interval between auto¬ 
key events, except for the first auto-key event. See 
also repeat delay. 


reserved memory: Memory not managed by 
the Memory Manager; that is, memory that is 
marked as busy at startup time. 

light scroll bar: The control the user selects to 
scroll vertically through the data in the window. 

ROM: See read-only-memory. 

ROM font: The font contained in system ROM. 

rounded result: The nearest representable value 
to the actual value, with ties going to the value with 
the larger magnitude. 

rounded-comer rectangle: One of the 
fundamental shapes drawn by QuickDraw II. The 
rounded corners of this type of rectangle are 
defined by an oval height and oval width. 

routine: A part of a program that accomplishes 
some task subordinate to the overall task of the 
program. 

RTL (Return from Subroutine Long): A 65816 
assembly-language instruction. 

RTS (Return from Subroutine): A 65816 
assembly-language instruction. 

SANE (Standard Apple Numeric 
Environment): The set of methods that 
provides the basis for floating-point calculations 
in Apple computers. SANE meets all requirements 
for extended-precision, floating-point arithmetic 
as prescribed by IEEE Standard 754 and ensures 
that all floating-point operations are performed 
consistendy and return the most accurate results 
possible. 

SANE Tool Set: The Apple IIGS tool set that 
performs high-precision, floating-point 
calculations, following SANE standards. 

scaled font: A font that is created by the Font 
Manager by calculation from a real font of a 
different size. 

scaling: The process of taking all characters of a 
real font and making them bigger or smaller to 
generate a requested font. 
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scan line: A single horizontal line of pixels on 
the screen. It corresponds to a single sweep of the 
electron gun in the video display tube. 

scan line control byte (SCB): A byte in 
memory that controls certain properties, such as 
available colors and number of pixels, for a scan 
line on the Apple IIGS. Each scan line has its own 
SCB. 

SCB: See scan line control byte. 

Scheduler: The Apple IIGS tool set that manages 
requests to execute interrupted software that is not 
reentrant. If, for example, an interrupt handler 
needs to make system software calls, it must do so 
through the Scheduler because ProDOS l6 is not 
reentrant. Applications normally need not use the 
Scheduler because ProDOS 16 is not in an 
interrupted state when it processes applications’ 
system calls. 

scrap count* A count that indicates how many 
times the desk scrap has changed. 

Scrap Manager: The Apple IIGS tool set that 
supports the desk scrap, which allows data to be 
copied from one application to another or from 
one place to another within an application. 

scroll: To move an image of a document or 
directory in its window so that a different part Of it 
is visible. 

scroll bar: A rectangular bar that may be along 
the right or bottom of a window. Clicking or 
dragging in the scroll bar causes the view of the 
document to change. 

selection range: The series of characters where 
the next editing action will occur. 

serial interface: A standard method, such as 
RS-232, for transmitting data serially (as a 
sequence of bits). 

serial port: The connector for a peripheral 
device that uses a serial interface. 

Shaston: The Apple IIGS system font. 


shut down: To remove from memory or 
otherwise make unavailable, as a tool set that is no 
longer needed or an application that has quit. 

single mode: In the List Manager, a selection 
mode that allows the user to select only one 
member of a list at once; that is, when the user 
drags the mouse, the selection moves from one 
member to another. 

65 C 8 I 6 : The microprocessor used in the 
Apple IIGS. The 65C816 is a CMOS device with a 
16 -bit data bus and a 24-bit address bus. 

6502: The microprocessor used in the Apple II, 
Apple II Plus, and early models of the Apple He. 
The 6502 is an NMOS device with 8-bit data 
registers and l6-bit address registers. 

65816 assembly language: A low-level 
programming language written for the 65816 
family of microprocessors. 

640 mode: An Apple IIGS video display mode, 
640 pixels horizontally by 200 pixels vertically. 

size box: A small region in the lower right corner 
of a window that the user can drag to change the 
size of the window. 

slop rectangle: The rectangle that allows the user 
some margin for error when moving the mouse. 

slot: A narrow socket inside the computer where 
the user can install peripheral cards. Also called 
expansion slot 

smoothing: A LaserWriter printing option that 
asks the system to smooth out any bit-mapped 
fonts with jagged edges. 

software: A collective term for programs, the 
instructions that tell the computer what to do. 
Software is usually stored on disks. Compare 

firmware, hardware. 

sound GLU (general logic unit): The interface 
chip between the system hardware and the sound 
hardware. 
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Sound Tool Set: The Apple IIGS tool set that 
provides low-level access to the sound hardware. 

source location: The location (memory buffer 
or portion of the QuickDraw II coordinate plane) 
from which data such as text or graphics are 
copied. See also destination rectangle. 

source rectangle: The rectangle Con the 
QuickDraw II coordinate plane) where text or 
graphics are drawn when transferred from 
somewhere else. Compare destination 
rectangle. 

special memory: On an Apple IIGS, all of banks 
$00 and $01 and all display memory in banks $E0 
and $E1. It is the memory directly accessed by 
standard Apple II programs running on the 
Apple IIGS. 

spool printing: A two-step printing method used 
to print graphics on the ImageWriter. In the first 
step, it writes out (spools) a representation of your 
document’s printed image to a disk file or to 
memory. The second step consists of this 
information being converted into a bit image and 
printed. Compare draft printing. 

S register: See stack register. 

SRQ list: A special tool mechanism that can be 
used to poll the Apple Desktop Bus for data from 
specific devices. 

SRQ list completion routine: Used in 
conjunction with the ADB Tool Set routine 
AsyncADBReceive, this completion routine 
obtains ADB data from a buffer. The only major 
difference between this routine and the 
AsyncADBReceive completion routine is that the 
SRQ list routine has an extra return address on the 
stack when it is called. Compare 
AsyncADBReceive completion routine. 


stack: A list in which entries are added (pushed) 
and removed (pulled) at one end only (the top of 
the stack), causing entries to be removed in last- 
in, first-out (UFO) order. The stack usually refers 
to the particular stack pointed to by the 65C8l6*s 
stack register. Compare queue. 

stack pointer: See stack register. 

stack register: A register in the 65816 processor 
that indicates the next available memory address 
in the stack. Also called S register. 

stage byte: Determines the actions taken by an 
alert See also alert stage. 

Standard Apple Numerics Environment: See 
SAIVE. 

Standard Apple 11: Any computer in the Apple II 
family except the Apple IIGS. That includes the 
original Apple n, the Apple II Plus, the Apple lie, 
and the Apple lie. Compare Apple n. 

Standard File Operations Tool Set: The 
Apple IIGS tool set that creates a standard user 
interface for opening and closing files. 

standard window controls: The window 
controls that allow the user to scroll through the 
data in the window, change the window’s shape, or 
close the window. They also provide information 
about the document currently displayed in the 
window. 

start up: To get the system, application 
program, or tool set running. 

static segment: A program segment that must 
be loaded when the program is started and cannot 
be removed from memory until execution 
terminates. Compare dynamic segment. 

static text: Text on the screen that cannot be 
altered by the user. 

string; A sequence of characters. See also 
C string, Pascal string. 
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string bounds rectangle: The smallest 
rectangle that would enclose all the foreground 
and background pixels of a string if the string were 
to be drawn. 

structure region: An entire window: its content 
region plus its frame region. 

style dialog box: A dialog box that allows the 
user to specify formatting information, page size, 
and printer options. 

styled variation: An italicized, bold, 
underlined, or otherwise altered version of a 
plain-styled charaaer or font. 

style subrecord: A data structure within the print 
record that contains information gathered from 
the user via the style and job dialog boxes. 

subdirectory: A file that contains information 
about other files.- In a hierarchical file system, files 
are accessed through the subdirectories that 
reference them. 

subroutine: A part of a program that can be 
executed on request from another point in the 
program and that, upon completion, returns 
control to the point of the request. 

Super Hi'Res: Either of two high-resolution 
Apple IIGS display modes: 320 mode consists of an 
array of pixels 320 wide by 200 high, with l6 
available colors; 640 mode is an array 640 wide by 
200 high, with l6 available colors (with 
restrictions). 

swap pair: A pair of oscillators that form a 
functional unit (called a generator) when the 
digital oscillator chip (DOC) is in swap mode. 

switcher: A program that rapidly transfers 
execution among several applications. 

switch event: An event that indicates the 
application is being returned to after being 
switched out of by a switcher-type application. 


synthesizer: (1) A hardware device capable of 
creating sound digitally and converting it into an 
analog waveform that you can hear. (2) By 
analogy, any sound-making entity, such as the 
Free-Form Synthesizer in the Sound Tool Set 

system clock: See clock (1). 

system disk: A disk that contains the operating 
system and other system software needed to run 
applications. 

system event mask: A set of flags that controls 
which event types get posted into the event queue 
by the Event Manager. 

system failure: The unintentional termination 
of program execution due to a severe software 
error. 

System Failure Manager: A part of the 
Miscellaneous Tool Set that processes fatal errors 
by displaying a message on the screen and halting 
execution. 

system folder: The SYSTEM/subdirectory on a 
ProDOS 16 system disk, 

system font: The font that QuickDraw II uses as 
the default current font when a new GrafPort is 
opened. 

System Loader; The program that manages the 
loading and relocation of load segments 
(programs) into the Apple IIGS memory. The 
System Loader works closely with ProDOS l6 and 
the Memory Manager. 

system menu bar: The menu bar that always 
appears at the top of the screen in desktop 
applications. It contains all of the commonly used 
functions such as File, Edit, and so on. Compare 

window menu bar. 

system software; The components of a 
computer system that support application 
programs by managing system resources such as 
memory and I/O devices. 

system window: A window in which a desk 
accessory is displayed. 
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task code: A numeric value assigned to the result 
of each event handled by TaskMaster. Compare 

event code. 

TaskMaster: A Window Manager routine that 
handles many typical events for an application. 
Applications may call TaskMaster instead of 
GetNextEvent. 

template: A data structure or set of parameters 
that defines the characteristics of a desktop 
feature, such as a window control. The 
NewWindow parameter list is a template that 
defines the appearance of a window to be opened 
by the NewWindow calk 

text block: A number of ASCII characters in a 
buffer, with the number specified separately. 

text buffer: A 1-bit-per-pixel pixel image 
reserved for the private use of the QuickDraw n 
text-drawing call. 

text file format (TFF): A file that consists of 
ASCII representations of characters. Compare 

object module format. 

text mode: One of eight possible interactions 
between pixels in text being drawn to the screen 
and pixels on the screen that fall under charaaers 
being drawn. Compare pen mode. 

Text Tool Set: The Apple IIGS tool set that 
provides an interface between Apple II character 
device drivers and applications running in native 
mode. 

TFF: See text file format. 

320 mode: An Apple IIGS video display mode, 
320 pixels horizontally by 200 pixels vertically. 

tick count: The (approximate) number of 
60th-second intervals since system startup, 

title bar: The horizontal bar at the top of a 
window that shows the name of the window's 
contents. The user can move the window by 
dragging the title bar. 

tool: See tool set. 


toolbox: See Apple IIGS Toolbox. 

Tool Locator: The Apple IIGS tool set that 
dispatches tool calls. The Tool Locator knows and 
retrieves the appropriate routine when your 
application makes a tool call. 

tool pointer table (TFT): A table, maintained 
by the Tool Locator, that contains pointers to all 
active tool sets. 

tool set: A group of related routines (usually in 
ROM) that perform necessary functions or provide 
programming convenience. They are available to 
applications and system software. The Memory 
Manager, the System Loader, and QuickDraw II are 
Apple IIGS tool sets. 

tool table: A list of all needed tool sets and their 
minimum required versions. An application 
constructs this table in order to load its tools with 
the LoadTools call. 

TFT: See tool pointer table. 

transfer mode: A specification of which 
Boolean operation QuickDraw II should perform 
when drawing. See, for example, XOR. 

TRUE: Not zero. The result of a Boolean 
operation. The opposite of FALSE. 

typelD: A subfield of the user ID. The User ID 
Manager assigns a typelD value based on the type 
of program (application, tool set, and so on) 
requesting the memory. 

unclaimed Interrupt: This occurs when the 
hardware Interrupt Request Line is active, 
indicating that an interrupt-producing device 
needs attention, but none of the installed interrupt 
handlers claims responsibility for the interrupt. 

underline: (1) A style of text. (2) A method used 
to separate groups of items in a menu. An 
underlined item does not use any more space, on 
the screen or in memory, than the item does 
without the underline. Compare dividing line. 
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unhighllght: To restore to normal display. 
Selected controls, menu items, or other objects 
may be highlighted (usually displayed in inverse 
colors) while in use and unhighUghted when not in 
use. 

unload: To remove a load segment from 
memory. To unload a segment, the System Loader 
does not actually “unload” anything; it calls the 
Memory Manager to either purge or dispose of the 
memory block in which the code segment resides. 

unlock: To permit the Memory Manager to move 
or purge a memory block if needed. Compare 

lock. 

unmovable: See fixed. 

unpack: To restore to normal format from a 
packed format. 

unpurgeable: Having a purge level of zero. The 
Memory Manager is not permitted to purge 
memory blocks whose purge level is zero. 

unreal font: A font that was scaled by the Font 
Manager from a real font of a different size or 
added by an application and marked as unreal 
Compare real font. 

update event: An event posted by the Window 
Manager when all or part of a window needs to be 
redrawn. 

user ID: An identification number that specifies 
the owner of every memory block allocated by the 
Memory Manager. User ID’s are assigned by the 
User ID Manager. 

User ID Manager: A part of the Miscellaneous 
Tool Set that is responsible for assigning user ID’s 
to every block of memory allocated by the 
Memory Manager. 

vector: A location that contains a value used to 
find the entry point address of a subroutine. 

view rectangle: The rectangle within which text 
in an edit record is visible; that is, the portion of 
the text in the destination rectangle that the user 
can see is determined by the view rectangle. 


visible region: The part of a window that’s 
actually visible on the screen. The visible region is 
defined by a GrafPort field manipulated by the 
Window Manager. 

voice: Any one of 16 pairs of oscillators in the 
Ensoniq sound chip on the Apple IIGS. 

wedge; A filled arc, one of the fundamental 
shapes drawn by QuickDraw II. 

window: A rectangular area that displays 
information on a desktop. You view a document 
through a window. You can open or close a 
window, move it around on the desktop, and 
sometimes change its size, scroll through it, and 
edit its contents. The area inside the window’s 
frame corresponds to the port rectangle of the 
window’s GrafPort. 

window definition procedure: A procedure 
used to define the appearance and behavior of a 
custom window. 

window frame: The outline of the entire window 
plus certain standard window controls. 

Window Manager: The Apple IIGS Tool Set that 
updates and maintains windows. 

window menu bar: A menu bar that appears at 
the top of the active window, below the system 
menu bar. It can contain document titles, 
applications, and functions. Compare system 
menu bar. 

window record: The internal representation of a 
window, where the Window Manager stores all the 
information it needs for its operations on that 
window. 

word; On the Apple IIGS, a l6-bit C2-byte) data 
type. Compare long, long word. 

X flag: One of three flag bits in the 65C816 
processor that programs use to control the 
processor’s operating modes. In native mode, the 
setting of the x flag determines whether the index 
registers are 8 bits wide or 16 bits wide. See also 
e flag, m flag. 
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XOR: Exclusive-OR. A Boolean operation in 
which the result is TRUE if, and only if, the two 
items being compared are unequal in value. 

X register: One of the two index registers in the 
65816 microprocessor. 

Y register: One of the two index registers in the 
65816 microprocessor. 

zero page: The first page (256 bytes) of memory 
in a standard Apple II computer (or in the 
Apple IIGS when running a standard Apple II 
program). Because the high-order byte of any 
address in this part of memory is zero, only a 
single byte is needed to specify a zero-page 
address. Compare direct page. 

2 flag: A bit in the 65816 processor’s Processor 
Status register that is set to 1 if the last operation 
resulted in 0 (zero). 

zoom box: A small box with a smaller box 
enclosed in it found on the right side of the tide 
bar of some windows. Clicking the zoom box 
expands the window to its maximum size; clicking 
it again returns the window to its original size. 

zoom region: The window region that 
corresponds to the zoom box. 
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arc tangent 9-13 
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ascent 16-26, 16-45, 16-48, 16-62 
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ASCII 9-8, 9-9, 9-25, 9-26, 9-29, 
9-30, 9-31, 9-33, 14-4, 14-16 
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AsyncADBReceive 3-3, 3-7-8, 
3-14, 3-27, 7-24 
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atBoundsRect 6-20, 6-32, 6-89 
athens 8-4, 8-51 
atItemList 6-89 
atStagel 6-20, 6-32, 6-89 
atStage2 6-20, 6-32, 6-89 
atStageS 6-20, 6-32, 6-89 
atStage4 6-20, 6-32, 6-89 
attrAddr 12-12-13, 12-49 
attrBank 12-12-13, 12-49 
attrErr 12-42, 12-47, B-2 
attrFixed 12-12-13, 12-49 
at tr Handle 12-47 
attributes word 12-12, 12-32, 
12-39 

attrLocked 12-12-13, 12-47 
attrNoCross 12-12-13, 12-47 
attrNoPurge 12-12-13, 12-47 
attrNoSpec 12-12-13, 12-47 
attrPage 12-12-13, 12-47 
attrPurge 12-12-13, 12-47 
attrPurgel 12-12-13, 12-47 
attrPurge2 12-12-13, 12-47 
attrPurge3 12-12-13, 12-47 
attrSystem 12-47 
auto-key event 6-39, 7-3, 7-13 
autoKeyEvt 7-7, 7-50, 25-120 
autoKeyMask 7-11, 7-50 
autoTrack 4-25, 4-36, 4-83, 4-86 
auxFileType 22-24, 22-32 
auxlD 12-10-11, 12-14, 12-15, 

14-58 

available font 8-1, 8-25, 8-36 
axisParam 4-33-34, 4-88 
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background 16-52 
background color 16-26, 16-54, 
16-57, 16 - 110 , 16-213, 16-226 

background pattern I 6 -I 8 , I 6 -III, 
16-214, 16-251 

background pixel 16-28, 16-30, 

16-52 

background procedure 15-24, 

15- 41 

BackGroundRgn 25-42, 25-139 
backslash character 5-8, 13-14 
Backspace 10-2, 10-29 
badColorNum 16-115, 16-220, 

16- 278, B-3 

badDevNum 23-15, 23-47, B-4 
badDevType 23-15, 23-28, 23-33, 
23 - 35 , 23-38, 23-47, B-4 
badFile 23-47 
badFormat 23-16, 23-47, B-4 
badInputErr 14-19, 14-57, 

14- 70, B-2 

badItemType 6-56, 6-57, 6-69, 
6-84, 6-90, B-5 
badLaserPrep 15-36, 15-42, 

15- 49, B-5 

badLPFile 15-36, 15-42, 15-49, 
B-5 

badMode 23-15, 23-47, B-4 
badRect 16-278, B-3 
badScanLine 16-250, 16-278, B-3 
badScrapType 20-10, 20-12, 
20-14, 20-19, B-5 
badTableNum 16-115, I 6 -II 6 , 

16 - 220 , 16 - 221 , 16-278, B-3 
badTitle 23-15, B-4 
barArrowBack 4-22, 4-87, 11-7 
barinactive 4-22, 4-87, 11-7 
barNorArrow 4-22, 4-87, 11-7 
barNorThumb 4-22, 4-87, 11-7 
barOutline 4-22, 4-87, 11-7 
barPageRgn 4-22, 4-87, 11-7 
barSelArrow 4-22, 4-87, 11-7 
barSelThumb 4-22, 4-87, 11-7 
base family 8-7, 8-12, 8-13 
base line 10-7, 16-26, 16-45 
baseOnlyBit 8-8, 8-50 
BASIC device driver 23-3 
basicType 23-46 


Battery RAM 14-4, 14-9, 14-10, 

14- 11, 14-13, 14-16 
parameter reference 

numbers 14-12 

BeginUpdate 4-54, 10-11, 10-46, 
25-11, 25 - 20 , 25 - 35 , 25-47, 
25-116, 25-119 
BELLI 14-53 
be 11 Vector 14-68 
bellVolume 14-65 
best-fit font algorithm 8-6, 
8-16-17, 8-44 
Better Color option 15-8 
Better Text option 15-8 
bFileVers 15-14, 15-15, 15-48 
bgColor 16 - 110 , 16-213 
bit plane 16-31 

bJDocLoop 15-14, 15-15, 15-37, 

15- 48 

black 16-274 
blinking caret 10-10, 10-26 
blinking menu item 13-76 
blink interval 10-26 
block 12-1. See also memory 
block 

fixed 12-7 
locked movable 12-7 
locking 12-31 
purging 12-8, 12-39, 12-40 
unlocking 12-32, 12-33 
BlockMove 12-21 
blue 16-274 
blueMask 16-274 
boldMask 16-276 
BOOLEAN XXX 
bottomMost 25-139 
bottom scroll bar 25-6 
boundary rectangle 16-13-17, 

16 - 232 

boundRect 4-33-34, 4-88 
boundsRect 16-13 
boxNor 4-18, 4-87 
boxReserved 4-18, 4-87 
boxSel 4-18, 4-87 
boxTitle 4-18, 4-87 
breakVector 14-68 
BringToFront 25-36 
brkVar 14-66 
brown320 16-274 
btn estate 7-9, 7-10, 7-51 
btnlState 7-9, 7-10, 7-51 
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bttnintrpt 14-36, 14-67 
bttnintrptvi 14-36, 14-67 
bttnNorBack 4-l6, 4-87 
bttnNorText 4-l6, 4-87 
bttnOrMove 14-36, 14-67 
bttnOrMoveVI 14-36, 14-67 
bttnOutline 4-l6, 4-87 
bttnSelBack 4-l6, 4-87 
bttnSelText 4-l6, 4-87 
BufDimRec 16-206, 16-276 
bufferSize 21-17, 21-37 
buffer-sizing record 16-205, 
16-206-207 

built-in CDA name 5-16, 5-23 
busy flag 5-3, 19-1, 19-3, A-1 
Button 7-14, 7-31, 7-47 
button 4-3, 4-14 
bold outline 4-14, 4-85 
cancel 6-4, 6-5, ^18, 6-58 
default 6-5, 6-11, 6-37 
disk 22-24, 22-31 
mouse 4-46 
OK 6-4, 6-5, 6-18, 6-58 
radio 4-4 

buttonitem 6-10, 6-88 
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C, calling routines from 2-6 
Cairo 8-4, 8-51 
calcCRect 4-25 

CalcMenuSize 13-13, 13-19, 13-33, 
13-37, 13-41, 13-58 
calcRect 4-86 
calling tool set routines 
assembly language 2-5 
C 2-6 

cancel 6-89 

cancel button 6-4, 6-5, 6-18, 6-21, 
6-58, 8-14 

cancelDefault 6-89 
can not Re set 16-278, B-3 
cant Sync 3-29, B-4 
capsLock 7-9, 7-51 
caret 7-36, 10-8, 10-9, 10-11, 
10-20, 10-34, 10-38, 10-46 
blinking 10-10, 10-26 
carriage return character 10-40, 
10-42 

carry flag. See c flag 
Caution alert 6-6 


Caution Alert 6-24, 6-35 
caution icon 6-35 
CDA header section 5-18 
CDA menu 5-3, 5-12, 5-21 
CDA name 5-16, 5-23 
c flag 2-5, 2-7, B-1 
Change Address command 3-4 
changeFlag 7-9, 7-10, 7-51 
change flag byte 10-43 
channel-generator type word 21-16 
character 16-26 
dead 16-45 
missing 16-48-49 
character bounds rectangle 16-28, 
16-52, 16-69, 16-76, 16-269 
character bounds width 16-52 
character device driver 1-4, 23-1, 
23-3 

character echo-flag word 23-29 
character image l6-26 
character image width 16-44 
character origin 16-26-27, 16-45 
character position 10-7 
character rectangle 16-44 
character width 16-26-27, 16-44, 
16-45, 16-51, 16-70, 16-77, 
16-267, 16-270 

CharBounds 16-29, 16-56, 16-58, 
16-69 

CharWidth 16-29, 16-56, 16-58, 
16-70 

check box 4-3, 4-10, 4-l6 
control record 4-16-18 
checkBox 4-86 
CheckHandle 12-22 
checkitem 6-10, 6-88 
CheckMItem 13-6, 13-34 
check?roc 4-13, 4-73, 4-85 
CheckUpdate 25-37 
chExtra 16-30. 16-51, 16-55, 

16-58, 16-59, 16-60, 16-112, 
16-217 

ChooseCDA 5-12 
ChooseFont 8-13, 8-14, 8-15, 
8-26-27, C-5 

Choose Printer dialog box 15-1, 
15-4-5 

chunky pixel 16-31 
clamp 

absolute 14-21 

absolute device 14-37, 14-38 


ClampMouse 7-27, 14-30 
clamp value 2-2, 7-27, 14-30, 
14-31 

classic desk accessory 5-1 
clear 5-30 

clear Act ion 5-7, 5-30 
Clear command 6-43 
clearModes 3-20, 3-28 
ClearMouse 14-31 
ClearScreen 16-71 
ClearSRQTable 3-15 
Clipboard 20-1, 20-5, 20-17 
clipping region 16-14-15, 16-17, 
16-72, 16-113, 16-114, 
16-187, 16-197, 16-208, 
16-218, 17-10 
ClipRect 6-7, 16-40, 16-72 
clipRgn 16-15, 16-219, 25-23, 
25-28 

clockFormat 14-65 
Close 5-14 
CloseAlINDAs 5-12 
close box 25-6, 25-8, 25-49 
CloseDialog 6-23, 6-36 
CloseNDA 5-6, 5-13 
CloseNDAbyWinPtr 5-6, 5-14, 
25-122 

ClosePicture 17-5, 17-9 
ClosePoly l6-40, 16-72 
ClosePort 16-39, 16-73 
CloseRgn 16-40, 16-74 
CloseWindow 4-9, 4-68, 11-11, 
11-16, 25-11, 25-29, 25-38, 
25-127 

CIrHeartBeat 14-53 
cmndincomplete 3-14, 3-17, 
3-18, 3-19, 3-25, 3-26, 3-27, 
3-29, B-4 

Collision Detect handler 3-4-5 
color 

background 16 - 26 , 16-213 
foreground 16-26, 16-228 
list 11-10 

window frame 25-18, 25-57, 
25-99 

window information bar 25-20 
window size box 25-19 
window title 25-18 
window title bar 25-19 
color box 15-8 
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colorMItemHilite 13-78, 13-87 
color palette. See palette 
color printing 15-8, 15-15-18 
colorReplace 13-72, 13-87 
color table 11-10, 13-43, 

16-31-33, 16-115, 16-116, 
16-158, 16 - 220 , 16-221 
alert window 25-17 
document window 25-17 
standard 16-159 
window 25-142 
colorTable 16-275 
comment 17-15 
compaction of memory 12-5, 
12-6-7, 12-15, 12-22 
CompactMem 12-22 
comparison routine 11-24 
completion routine 3-7-9, 3-25 
AsyncADBReceive 3-8 
SRQ list 3-9 

connector specification xxvi 
constants 

Apple Desktop Bus Tool Set 
3-28-29 

Control Manager 4-85-86 
Desk Manager 5-30 
Dialog Manager 6-88-89 
Event Manager 7-50-51 
Font Manager 8-50-51 
Integer Math Tool Set 9-42 
LineEdit Tool Set 10-47 
List Manager 11-25 
Memory Manager 12-47 
Menu Manager 13-87 
Miscellaneous Tool Set 14-64-68 
Print Manager 15-47 
QuickDraw II 16-274-76 
Scrap Manager 20-19 
Sound Tool Set 21-36-37 
Standard File Operations Tool 
Set 22-32 

Text Tool Set 23-46 
Tool Locator 24-26 
Window Manager 25-139-141 
conTable320 16-107 
conTablG640 16-107 
content height, maximum 25-87 


content region 4-8, 25-9, 25-12, 
25-35, 25-51, 25-53, 25-60, 
25-62, 25-64, 25-83, 25-87, 
25-88, 25-92, 25-94, 25-96, 
25-103, 25-105, 25-106, 
25-131, 25-132 

content width, maximum 25-87 
control 1-3, 4-1 
active 4-7 
custom 4-24 
defining 4-24-40 
highlighted 4-7 
inactive 4-7 
standard 4-3-4 
window 4-8, 25-6-7 
control code 23-15 
control definition procedure 4-24, 
4-46, 4-73, 11-1, 11-11 
Control-F 10-2, 10-29 
control flag 4-12, 4-13, 4-72 
check box 4-18 
radio button 4-14 
scroll bar 4-22 
simple button 4-l6 
size box 4-20 
controlKey 7-9, 7-51 
control list 25-68 
Control Manager 1-3, 1-5, 4-1-88, 

6- 28, 25-9 
constants 4-85-86 
data structures 4-87-88 
error codes 4-88 

icon font 4-11 
part codes 4-8 
shutdown routine 4-43 
startup routine 4-42 
status routine 4-44 
using 4-9-10 

version number routine 4-43 
Control Panel 3-1, 5-3, 5-22, 6-21, 

7- 3, 7-36, 7-37, 10-26, 13-76 
control record 4-11-24 

check box 4-16-18 
radio button 4-18-20 
scroll bar 4-20-22 
simple button 4-14-16 
size box 4-23-24 
Control-X 10-2, 10-29 
Control-Y 10-2, 10-29 


conventions 
bol(l£ace xxxi 
Courier xxxi 
italic xxxi 

coordinate plane 16-9-14 
copies 15-8 
copMgr 14-67 
copy 5-30 

copyAction 5-7, 5-30 
Copy command 6-41, 20-1, 20-6 
CopyPixels 17-5, 17-10 
CopyRgn 16-75 
cosine 9-20 
CountFamilies 8-28 
CountFonts 8-15, 8-29-30 
CountMItems 13-13, 13-35 
count word 14-49 
Courier xxxi, 8-4, 8-51 
CreateControl 11-10 
CreateList 11-5, 11-11, 11-16, 
11-23 

crsrUpdtHnd 14-68 
crWidth 15-12, 15-13 
C string 16-26, l6-4l 
cString 11-25 
CStringBounds 16-29, 16-58, 
16-76 

CStringWidth 16-29, 16-58, 16-77 
ctlAction 4-12, 4-13, 4-15, 4-19, 
4-21, 4-23, 4-59, 4-74, 4-87, 
11-6, 13-17 
CtlBootlnit 4-41 
ctlColor 4-12, 4-14, 4-15, 4-l6, 
4-17, 4-19, 4-21, 4-23, 4-87, 
11-6, 11-10, 13-17 
ctlData 4-12, 4-14, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-63, 4-78, 
4-87, 11-6, 13-17 
ctlFlag 4-12, 4-13, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-87, 11-6, 
13-17 

ctlHilite 4-12, 4-13, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-87, 11-6, 
13-17 

ctlinVis 4-16, 4-18, 4-20, 4-22, 
4-24, 4-72, 4-80, 4-85 
ctlList 11-6, 11-26 
ctlListBar 11-6, 11-26 
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ctlMemDraw 11-6, 11-26 
ctlMemHeight 11-6, 11-26 
ctlMemSize 11-6, 11-26 
CtlNewRes 4-45 
ctlNext 4-12, 4-13, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-87, 11 - 6 , 
13-17 

ctlOumer 4-12, 4-13, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-87, 11 - 6 , 
13-17 

ctlProc 4-12, 4-13, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-87, 11 - 6 , 
13-17 

ctlRect 4-12, 4-13, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-87, 11 - 6 , 
13-17 

ctlRefcon 4-12, 4-14, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-62, 4-77, 
4-87, 11 - 6 , 13-17 
CtlReset 4-44 
CtlShutDown 4-9, 4-43 
CtlStartUp 4-9, 4-42 
CtlStatus 4-44 
CtlTextDev 23-15-16 
ctlValue 4-12, 4-13, 4-15, 4-17, 
4-19, 4-21, 4-23, 4-64, 4-79, 
4-87, 11 - 6 , 13-17 
CtlVersion 4-43 
ctlYVector 14-68 
current font 8 - 8 , 16 - 26 , 16 - 119 , 
16-224 

current icon font 25-109 
cursor 16-37-38, 16-156, I 6 -I 6 O, 
16 - 182 , 16 - 222 , 16 - 230 , 
16-264, 17 - 16 , 25-46 
curs or Act ion 5-7, 5-30 
cursor record 16-37, 16-117, 

16-222 

custom control 4-24 
custom menu 13-6 
customMenu 13-72, 13-87 
cut 5-30 

cutAction 5-7, 5-30 

Cut command 6-42, 20-1, 20-6 


D 

daNotFound 5-14, 5-20, 5-30, B-3 
darkGray320 16-274 
darkGreGn320 16-274 
data area 25-9-10, 25-54, 25-87, 
25-96, 25-97 
data bank 25-43 
data structures 

Apple Desktop Bus Tool Set 
3-29 

Control Manager 4-87-88 
Dialog Manager 6-89-90 
Event Manager 7-51 
Font Manager 8-51 
LineEdit Tool Set 10-47 
List Manager 11-25-26 
Menu Manager 13-88 
Miscellaneous Tool Set 14-69 
Print Manager 15-47-48 
QuickDraw II 16-276-278 
Sound Tool Set 21-37 
Standard File Operations Tool 
Set 22-32 

Window Manager 25-142-143 
dateFormat 14-65 
dblClkTime 14-65 
dead character 16-45 
deallocation of memory 12-1, 

12 - 23 , 12-24 

decBsyFlag 14-68 
Dec2Int 9-8 
Dec2Long 9-9 

default button 6-5, 6-11, 6-18, 
6-21, 6-24, 6-37, 6-51, 6-80 
DefaultFilter ^37 
defProcParm 6-90 
DeletelD 14-59 

DeleteMenu 13-13, 13-36, 13-39 
deleteMessage 24-15, 24-26 
DeleteMItem 13-13, 13-37 
DelHeartBeat 7-25, 14-52 
delta flag byte 10-43 
dep)endencies C-1-5 
dereference 12-5 
descender 16-45 
descent 16-26, 16-45, 16-48, 

16-62 


descent line 16-45 
DESK.ACCS subdirectory 5-3, 5-6 
desk accessory 1-3, 5-1 
altemate-display-mode 5-24 
classic 5-1 
new 5-1 

desk accessory event 7-4, 7-14 
Desk Accessory menu 13-4-5 
deskAccEvt 7-7, 7-50 
deskAccHnd 14-^ 
deskAccMask 7-11, 7-50 
DeskBootInit 5-9 
Desk Manager 1-3, 1-5, 5-1-30 
constants 5-30 
error codes 5-30 
GetNextEvent and 7-40 
shutdown routine 5-10 
startup routine 5-9 
status routine 5-11 
version number routine 5-10 
DeskReset 5-11 
desk scrap 1-3, 10-11, 10-23, 

10 - 45 , 20 - 1 , 20-3, 20 - 5-6 

data typ>es 20-3-^ 
DeskShutDown 5-4, 5-5, 5-6, 5-7, 
5-10 

DeskStanUp 5-4, 5-5, 5-6, 5-7, 5-9 
DeskStatus 5-11 
Desktop 25-39^3 
desktop 25-1, 25-39, 25-91 
desktop pattern 25-43 
desktop user interface xxvi 
DeskVersion 5-10 
destination rectangle 10-4, 10-6-7, 
10-36 

development environment xxvii 
devErr 23-16, 23-47, B-4 
device driver 3-3, 7-21 
installing 7-23-24 
removing 7-25 
writing 7-21-23 
device driver entry point 23-3 
device driver event 7-4 
devNotAtAddr 3-25, 3-29, B-4 
dial 4-4 

DialogBootInit 6-27 
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dialog box 1-3, 6-1, 6-4-6 
modal 6-5 
modeless 6-5 
standard 22-3 
dialog item type 6-10-11 
Dialog Manager 1-3, 1-6, 6-1-90, 
24-21 

constants 6-88-89 
data structures 6-89-90 
error codes 6-90 
shutdown routines 6-29 
startup routines 6-28 
status routines 6-30 
using 6-23-24 

version number routines 6-29 
dialog pointer 6-19 
dialog record 6-19 
DialogReset 6-30 
dialog scroll bar action procedure 
6-15 

DialogSelect 6-24, 6-38-39 
DialogShutDown 6-23, 6-29 
DialogSuitUp 6-23, 6-28 
DialogStatus 6-30 
dialog template 6-60, 22-4-12, 
22-26, 22-29 
DialogVersion 6-29 
dialog window 6-7 
DiffRgn 16-78 

digital oscillator chip (DOC) 21-3 
dimmed menu item 13-6, 13-38, 
13-60 

direct page 6-28, 25-43 
SANE 18-6, 18-9 
direct-page space 2-2, 4-42, 7-27, 
10-13, 12-13, 13-30, 15-26, 
16-64, 18-12, 21-8, 22-16 
DisableDItem 6-40, 6-82 
disableltem 13-78, 13-87 
disabled menu item 13-6, 13-38 
disableinc 21-23, 21-36 
disable increment 21-23, 21-35 
disableMenu 13-72, 13-87 
DisableMItem 13-6, 13-38 
disableSRQ 3-21, 3-28 
Disk button 22-24, 22-31 
dispctl 4-25, 4-30, 4-86 
displayMode word 17-4 
display rectangle 6-17, 6-52, 6-81 


displaySelect 22-22, 22-32 
DisposeAll 12-11, 12-14, 12-15, 
12-23 

DisposeControI 4-9, 4-45, 11-11 
DisposeHandle 12-23, 12-24 
DisposeMenu 13-36, 13-39, 13-67 
DisposeRgn 16-40, 16-79 
DisposeWindow 25-29 
dithering 4-52, 16-35, 25-104 
divByZeroErr 14-70, B-1 
dividing line 13-6, 13-15-16 
DlgCopy 6-24, 6-41 
DlgCut 6-24, 6-42 
DlgDelete 6-24, 6-43 
DlgPaste 6-24, 6-44 
DOC. See digital oscillator chip 
docAddrRngErr 21-24, 21-28, 
21-37, B-3 

docBuffer 21-17, 21-37 
DOC RAM 21-4, 21-24, 21-28, 
21-31, 21-32 

DOC registers 21-4, 21-29, 21-30 
document window 25-6 
color table 25-17 
DOC volume register 21-21 
dontScaleBit 8-44, 8-50 
dot operator 2-6 
DoWindows 7-12, 7-32 
downArrow 4-86 
down Flag 4-17, 4-72, 4-85 
Draft option 15-8 
draft printing 15-14-15, 15-20, 
15-23, 15-37 

DragControI 4-46-47, 11-11 
dr a get 1 4-25, 4-35, 4-86 
dragPatt 4-33-34, 4-88 
DragRect 4-48-49 
parameters 4-50-53 
drag region 25-9, 25-44, 25-49 
DragWindow 25-11, 25-44-46, 
25-124 

DrawChar 16-54, 16-57, 16-80 
DrawControls 4-9, 4-54, 11-11 
DrawCString 16-57,, 16-81 
drawCtl 4-25, 4-26, 4-86 
DrawDialog 6-45 
Drawicon 17-4, 17-5, 17-11 
drawing mask 16-18 


drawing on the screen 16-12 
drawing space 16-10, 16-57 
DrawMember 11^8, 11-17, 11-23 
DrawMenuBar 13-9, 13-30, 13-36, 
13-40, 13-57, 13-72 
DrawOneCtI 4-55, 11-11 
DrawPicture 15-38, 16-25, 17-5, 
17-12 

Drawstring 16-54, 16-57, 16-82, 
25-23 

DrawText 16-57, 16-83, 25-23 
driverEvt 7-7, 7-50 
driverMask 7-11, 7-50 
DRIVERS subdirectory 15-23, 
15-24 

dspBckColor 14-64 
dspBrdColor 14-64 
dspColMono 14-64 
dsp40or80 14-64 
dspTxtColor 14-64 
dtBoundsRect 6-60, 6-90 
dtItemList 6-60, 6-90 
dtRefCon 6-60, 6-90 
divisible 6-60, 6-90 
dualSpeed 14-65 
dupFile 23-15, 23-47, B-4 

E 

echo 23-46 

echo-flag word 23-29, 23-40 
edit Line 6-10, 6-11, 6-12, 6-17, 
6-39, 6-88 

edit record 10-4-5, 10-10-11 
allocating 10-10, 10-30 
disposing 10-22 
handle 10-10, 10-24 
text length 10-25 
emBadBttnNoErr 7-31, 7-49, 

7-52, B.3 

emBadEvtCodeErr 7-44, 7-52, B-3 
emBadEvtQErr 7-52, B-3 
emBadQHndlErr 7-52, B-3 
embedded changes 10-43-44 
EMBootInit 7-26 
emDupStrtUpErr 7-28, 7-52, B-3 
emNoMemQueueErr 7-28, 7-52, B-3 
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emNotActErr 7-52, B-3 
empty Err 12-28, 12-29, 12-38, 
12-43, 12-47, B-2 
empty handle 12-8 
empty rectangle 16-182 
Empty Rgn 16-84 
emQSiz2LrgErr 7-28, 7-52, B-3 
EMReset 7-30 
emResetErr 7-30, 7-52, B-3 
EMShutDown 7-12, 7-29 
EMStartUp 2-2, 7-12, 7-27-28 
EMStatus 7-30 
emulation mode 1-2 
emulation-mode entry point 14-5, 
14-17 

EMVersion 7-29 
EnableDItem 6-46, 6-82 
enable Item 13-78, 13-87 
enableMenu 13-72, 13-87 
EnableMltem 13-6, 13-40 
enableSRQ 3-21, 3-28 
EndInfoDrawing 25-47, 25-117 
EndUpdate 4-54, 10-11, 10-46, 
25-11, 25-20, 25-35, 25-47, 
25-116, 25-119 
Equal? t 16-85 
EqualRect 16-86 
EqualRgn 16-87 
equate file 2-5 
EraseArc 16-88 
EraseControl 4-56, 11-11 
EraseOval 16-89 
ErasePoly 16-90, 16-103 
EraseRect 10-11, 10-40, 10-42, 
10-46, 16-91 
EraseRgn 16-92 
EraseRRect 16-93 
erasing 16-18, 16-20 
error 2-5 
error codes 2-5 
Apple Desktop Bus Tool Set 
3-29 

Control Manager 4-88 
Desk Manager 5-30 
Dialog Manager 6-90 
Event Manager 7-52 
Font Manager 8-52 


Integer Math Tool Set 9-42 
LineEdit Tool Set 10-48 
Memory Manager 12-47 
Miscellaneous Tool Set 14-70 
Print Manager 15-34, 15-44, 
15-49 

QuickDraw II 16-278 
Scrap Manager 20-19 
Sound Tool Set 21-37 
system failure 14-55-56 
Text Tool Set 23-47 
Tool Locator 24-26 
tool set B-1-5 
Window Manager 25-144 
errorOutput 23-46 
error output text device 23-17, 
23-18, 23-19, 23-20, 23-21, 
23-22, 23-23, 23-32, 23-33 
ErrorSound 6-47 
ErrWriteBlock 23-17 
ErrWriteChar 23-18 
ErrWriteCString 23-7, 23-19 
ErrWriteLine 23-20 
ErrWriteString 23-21 
event 7-1 

activate 7-4, 7-5, 7-14, 10-16, 
10-20, 25-24 
application 7-4 
application-defined 7-14 
asynchronous 7-15-18 
auto-key 7-3, 7-13 
desk accessory 7-4, 7-14 
device driver 7-4 
keyboard 7-3, 7-13 
key-down 6-39, 6-66, 7-3, 7-13 
mouse-down 6-39, 6-64, 6-66, 
7-3, 7-13, 25-11, 25-48-49, 
25-127, 25-129-130 
mouse-up 7-3, 7-13 
priority 7-4-5, 7-40 
switch 7-4, 7-5, 7-14, 7-46 
types 7-3-4 

update 10-46, 25-52, 25-94, 
25-95, 25-96 
window 7-4, 7-14 


eventAction 5-7, 5-30 
EventAvail 7-5, 7-33 
event code 7-7 

event-driven application xxv, 2-2, 
7-1 

Event Manager 1-3, 1-6-7, 2-2, 
7-1-52, 14-5 
constants 7-50-51 
data structures 7-51 
error codes 7-52 
high-level 7-3 
low-level 7-3 
shutdown routines 7-29 
startup routines 7-27-28 
status routines 7-30 
using 7-12-15 

version number routines 7-29 
event mask 7-10-11, 7-39, 7-41, 
7-42 

system 7-10, 7-45 
event message 7-8 
event priority 7-4-5, 7-40 
event queue 2-2, 7-5, 7-27, 7-35, 

7- 39, 7-45 

event record 7-6, 25-45, 25-48 
modifier flags 7-8-10 
everyEvent 7-50 
evMgrData 14-66 
expansion of memory 12-3 
extended value xxx, 9-1 
extVCGHnd 14-68 
extVGCInt 14-24, 14-66 
exVCGDisable 14-26, 14-67 
exVCGEnable 14-26, 14-67 

F 

FakeMouse 7-23, 7-34 
fAlert 25-85-86, 25-141 
fAllocated 25-141 
family 16-43 
family 4-85 

family name 8-3, 8-32, 8-41, 8-42 
family number 8^4, 8-31, 8-32, 

8- 41, 8-42, 8-45 
famNum 8-6, 8-51 
FamNum2ItemID 8-31, 8-36 
FamSpecBits 8-11-12 
FamStatBits 8-12 
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fbrExtent 16-43, 16-53-54, 16-59, 
16-216 

fBScroll 25-85-86, 25-141 
fClose 25-85-86, 25-141 
fCtlTie 25-85-86, 25-120, 

25-141 

feed 15-12, 15-13, 15-48 
FFGeneratorStatus 21-11-12 
fFlex 25-85-86, 25-141 
FFSoundDoneStatus 21-13 
FFSoundStatus 21-14 
FFStartSound 21-15-17 
FFStopSound 21-18-20 
ffSynth 21-37 
ffSynthMode 21-36 
fgColor 16-125 
fgFbrExtent 16-62 
fgFontID 16-62 
fGrow 25-85-86, 25-141 
fgSize 16-62 
fgStyle 16-62 
fgVersion 16-62 
fgWidMax 16-62 
fHilited 25-85-86, 25-141 
file format xxvii 
flleInfoType 24-26 
filename 22-20 
fileName 22-24, 22-32 
file type 22-23 
fileType 22-24, 22-32 
FillArc 16-94 
filling 16-20 
fill mode 16-34 
FillOval 16-95 
FillPoly 16-96, 16-103 
FillRect 16-97 
FillRgn 16-98 
FillRRect 16-99 
filter procedure 6-22, 6-25-26, 
6-33, 6-37, 6-66, 22-22 
standard 6-25 
/Imaging 15-41, 15-48 
FindControl 4-10, 4-57-58 
FindDItem 6-48 
FindFamlly 8-15, 8-32-33 
FindFontStats 8-15, 8-34-35 
FindHandle 12-25 


FindWindow 4-10, 4-58, 5-26, 
13-12, 13-66, 25-11, 

25-48-49, 25-123, 25-124, 
25-125, 25-126 
finfo 25-85-86, 25-141 
firmTaskErr 14-70, B-2 
firstitem 13-19, 13-20, 13-88 
FixAppleMenu 5-5, 5-6, 5-8, 5-15, 
5-20 

FixATan2 9-13 
FixDiv 9-14 
fixed block 12-7 
fbced value xxx 9-1 
fixed-width font 16-226 
FixFontMenu 8-14, 8-15, 8-31, 
8-36-37, 8-45, C-5 
FixMenuBar 13-8, 13-9, 13-13, 13- 
33, 13-41 
FixMul 9-15 

FixRatio 9-16, 16-217, 16-253 

FixRound 9-17 

Fix2Frac 9-10 

Fix2Long 9-11 

Fix2X 9-12 

flag 2-7 

FlashMenuBar 13-13, 13-41 
flashRate 14-65 
flash320 16-275 
flshBufHnd 14-68 
flushADBDevBuf 3-21, 3-28 
FlushEvents 7-14, 7-35, 7-39 
flushKbd 3-20, 3-28 
fMapTrshdErr 14-55, 14-70, B-2 
fmBadFamNumErr 8-23, 8-26, 

8-29, 8-35 , 8-40, 8-41, 8-43, 
8-46, 8-49, 8-52, B-5 
fmBadNameErr 8-23, 8-42, 8-52, 
B-5 

fmBadSizeErr 8-26, 8-29, 8-35, 
8-40, 8-43, 8-46, 8-49, 8-52, 
B-5 

FMBootInit 8-18 

fmDupStartUpErr 8-20, 8-52, B-5 
fmFamNotFndErr 8-24, 8-31, 

8-45, 8-52, B-5 

fmFontMemErr 8-49, 8-52, B-5 
fmFontNtFndErr 8-40, 8-49, 

8-52, B-5 

FMGetCurFID 8-38 


FMGetSysFID 8-39 
fmMenuErr 8-31, 8-45, 8-52, B-5 
fmNotActiveErr 8-21, 8-52, B-5 
fMove 25-85-86, 25-141 
FMReset 8-22 
fmResetErr 8-22, 8-52, B-5 
fmScaleSizeErr 8-43, 8-52, B-5 
FMSetSysFont 8-15, 8-19, 8-40 
FMShutDown 8-15, 8-21 
FMStartUp 8-15, 8-19-20 
FMStatus 8-22 

fmSysFontErr 8-49, 8-52, B-5 
FMVersion 8-21 
font 6-79, 8-1, 16-26 
available 8-1, 8-25 
best-fit algorithm 8-l6, 8-43 
Control Manager icon 4-11, 8-16 
current 8-8, 16-26, 16-119, 
16-224 

current icon 25-109 
icon 25-15, 25-109 
real 8-7 

system 8-8, 8-39, 8-40, 8-48, 
16-147, 16-256 
unreal 8-7 

font bounds rectangle 16-53-54 
font definition 16-41-44 
font family 8-3, 8-28 
font flags 16-120, 16-225-226, 
16-274 

fontFlags 16-30, 16-56, 16-277 
font globals record 16-62, 16-118, 
16-121, 16-276 
fontHandle 16-26, 16-277 
font ID 2-6, 8-6, 8-l6, 16-122, 
16-224, 16-277 

font info record 16-62, 16-163, 
16-226, 16-276 

Font Manager 1-4, 1-7, 8-1-52, 
10-45, 16-227 
constants 8-50-51 
data structures 8-51 
error codes 8-52 
shutdown routine 8-21 
startup routine 8-19-20 
status routine 8-22 
using 8-14-16 
version number routine 8-21 
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font record 16-41-44, 16-276 
font rectangle l6-47<-48, 16-51 
font scaling 8-7-8, 8-44 
font size 8-4 
fontSize 8-6, 8-51 
FontSpecBits 8-8, 8-11 
FONTS subdirectory 8-1, 8-7, 

8-15, 8-19, 8-42 
FontStatBits 8-8-10, 8-35 
FontStatRec 8-10, 8-34, 8-51 
font strike 16-26, 16-41, 16-44, 
16-48-49 
font style 8-5 
fontStyle 8-6, 8-51 
font substitution 15-7 
fontWidth l6-6l, 16-206, 16-276 
ForceBufDims 16-58-60, 16-100 
foreground color 16-26, 16-54, 
16-57, 16-125, 16-226, 16-228 
foreground pixel l6-27, 1^30, 
16-52 

fPgDirty 15-41, 15-48 
FPT. See function pointer table 
fQContent 25-85-86, 25-124, 
25-141 

FracCos 9-20 

FracDiv 9-21 

FracMul 9-22 

FracSin 9-23 

FracSqrt 9-24 

Frac2Fix 9-18 

Frac2X 9-19 

frac value xxx, 9-1 

fragmentation of memory 12-6-8 

FrameArc 16-101 

frame color 25-99 

frameColor 25-18, 25-142 

FrameOval 16-102 

FramePoly 16-103 

FrameRect 16-104 

frame region 25-9 

FrameRgn 16-105 

FrameRRect 16-106 

frame type 25-69 

framing 16-20 

Free-Form Synthesizer playing 
status 21-13 
FreeMem 12-26 


freqOffset 21-17, 21-37 
FromDesk 25-40, 25-139 
FrontWindow 25-50, 25-56 
fRScroll 25-85-86, 25-141 
fstSpDelKey 14-65 
fTitle 25-141 

full native mode. See native mode 
fullPathname 22-24, 22-32 
funcNotFoundErr 24-7, 24-26, 

B-2 

function number A-3 

function pointer table (FPT) 24-7, 

24- 8, 24-19, A-2, A-6 
fvis 25-85-86, 25-141 
FWEntry 6-22, 14-5, 14-17-18 
fZoom 25-85-86, 25-141 
fZoomed 25-85-86, 25-112, 

25- 141 

G 

GCB. See generator control block 
gcbAddrTable 21-23, 21-36 
gen Avail 21-37 
genBusyErr 21-15, 21-37, B-3 
genSoff 21-36 
genlloff 21-36 
generator 21-5 
generator control block (GCB) 

21-6, 21-11 

address table 21-22, 21-23 
generator status word 21-12 
generator table 21-22, 21-23 
generator-to-oscillator 

translation 21-29 
geneva 8-4, 8-51 
genOoff 21-19, 21-36 
genloff 21-19, 21-36 
genZoff 21-19, 21-36 
genSoff 21-19, 21-36 
gen4off 21-19, 21-36 
genSoff 21-19, 21-36 
gen6off 21-19, 21-36 
gen7off 21-19, 21-36 
gen9off 21-19, 21-36 
genlOoff 21-19, 21-36 
genlZoff 21-19, 21-36 
genlSoff 21-19, 21-36 
genl4off 21-19, 21-36 
genTable 21-23, 21-36 


GetAbsClamp 14-5, 14-38 
GetAbsScale 3-15 
GetAddr 7-22, 14-5, 14-19-21 
parameter reference 
numbers 14-20 
Get Address 16-107-108 
GetAlertStage 6-49 
GetArcRot 16-109 
GetBackColor 16-55, 16-110 
GetBackPat 16-111 
GetBar Colors 13-42-43 
GetCaretTime 7-15, 7-36 
GetCharExtra 16-55, 16-112 
GetClip 16-40, 16-113 
GetClipHandle 16-114 
GetColorEntry 16-115 
GetColorTable I 6 -II 6 
GetContentDraw 25-51 
GetContentOrgin 25-52 
GetContentRgn 25-53 
GetControlDItem 6-23, 6-50 
GetQIAction 4-59 
GetCtiDpage 4-60 
GetQlParams 4-6l 
GetCtlRefCon 4-62 
GetCtlTitle 4-63 
GetaiValue 4-10, 4-64 
Get Cursor Adr 16-117 
GetDAStrPtr 5-16 
GetDataSize 25-54 
GetDblTime 7-13, 7-37 
GetDefButton 6-24, 6-51 
GetDefProc 25-55 
GetDeskPat 25-41, 25-139 
Get Desktop 25-40, 25-139 
GetDItemBox 6-52 
GetDItemType 6-53 
GetDItemValue 6-12, 6-54 
GetErrGlobals 23-22 
GetErrorDevice 23-23 
GetFamInfo 8-15, 8-23, 8-4l 
GetFamNum 8-15, 8-23, 8-42 
GetFGSize 16-62, I 6 -II 8 
GetFGSizecalls 16-62 
GetFirstDItem 6-55 
GetFirstWindow 25-56 
GetFont 8 -I 6 , 16-119 
GetFontFlags 16-56, 16-120 
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GetFontGlobals 16-30, 16-62, 
16 - 121 , 16-124, 16-150 
GetFontID 8-l6, 16-122 
GetFontInfo 16-62, 16-123 
GetFontLore 16-30, 16-62, 

16-118, 16-121, 16-124, 

16-150 

GetForeColor 16-55, 16-125 
GetFrameColor 25-20, 25-57 
GetFuncPtr 24-3, 24-7 
GetGrafProcs 16-126 
GetHandle 13-39 
GetHandleSize 12-27 
GetInfoDraw 25-58 
GetInfoRefCon 25-59 
GetInGIobals 23-24 
getInitTotal 6-15, 6-88 
getInitValue 6-15, 6-88 
getinitview 6-15, 6-88 
GetInputDevice 23-25 
GetIRQEnable 14-5, 14-23-24 
GetIText 6-23, 6-56 
GetListDefProc 11-18 
GetMasterSCB 16-127 
GetMaxGrow 25-60 
GetMenuBar 13-44 
GetMenuFlag 13-45 
GetMenuMgrPort 13-46 
GetMenuTitle 13-47 
getMessage 24-15, 24-26 
GetMHandle 13-39, 13-48 
GetMItem 13-16, 13-49 
GetMItemFlag 13-50 
GelMItemMark 13-6, 13-51 
GetMItemStyle 13-6, 13-52 
GetMouse 7-14, 7-38 
GetMouseClamp 14-31 
GetMTitleStart 13-53 
GetMTitleWidth 13-54 
GetNewDItem 6-23, 6-57-58 
GetNewID 12-11, 12-35, 14-57-58 
GetNewModalDialog 6-7, 6-23, 
6-59-60, 22-4 
GetNextDItem 6-6l 
GetNextEvent 4-10, 5-3, 6-33, 

6- 63, 6-66, 7-5, 7-12, 7-33, 

7- 39-40, 13-11, 25-11, 25-12, 
25-118, 25-119 

Desk Manager and 7-40 
GetNextWindow 25-56, 25-61 


GetNumNDAs 5-17 
GetOSEvent 7-41 
GetOutGlobals 23-26 
GetOutputDevice 23-27 
GetPage 25-62 
GetPen 16-128 
GetPenMask 16-129 
GetPenMode 16-130 
GetPenPat 16-131 
GetPenSize 16-132 
GetPenState 16-133 
GetPicSave 16-134 
GetPixel 16-135 
GetPolySave 16-136 
GetPort 16-39, 16-137, 25-21 
GetPortLoc 16-138 
GetPortRect 16-139 
GetRectInfo 25-63 
GetRgnSave 16-140 
GetRomFont 16-141-142 
GetSCB 16-143 
GetScrap 20-5, 20-6, 20-10 
GetScrapCount 20-5, 20-11 
GetScrapHandle 20-12 
GetScrapPath 20-13 
GetScrapSize 20-14 
GetScrapState 20-15 
GetScroll 25-64 
GetSoundVolume 21-21 
GetSpaceExtra 16-55, 16-144 
GetStandardSCB 16-145 
GetStructRgn 25-65 
GetSysBar 13-55 
GetSysField 16-146 
GetSysFont 16-147 
GetSysWFlag 25-66 
GetTableAddress 21-6, 21-22-23 
GetTextFace 16-56, 16-148 
GetTextMode 16-55, 16-149 
GetTextSize 16-150 
GetTick 14-22 
GetTSPtr 24-3, 24-8 
GetUpdateRgn 25-67 
GetUserField 16-151 
GetVector 7-23, 14-5, 14-61, 
14-63 

GetVisDesktop 25-41, 25-139 
GetVisHandle 16-152 
GetVisRgn 16-153 
GetWAP 24-3, 24-9 


GetWControIs 25-68 
GetWFrame 25-69 
GetWKind 25-70 
GetWMgrCon 25-72 
GetWMgrPort 25-71 
GetWTitle 25-73 
GetZoomRect 25-74 
global coordinates 4-50, l6-9, 
16-16, 16-39, 16-154, 16-173, 
25-29, 25-47 

GlobalToLocal 16-39, 16-154 
go-away region 25-9, 25-127 
good 22-24, 22-32 
GrafOff 16-155 
GrafOn 16-155 

GrafPort 16-14-15, 16-39, 16-187, 
16-241, 16-277, 25-17 
current 16-241 
standard 16-187 
grafProcs 16-126, 16-229, 

16-277 

graphic object 16-21 
graphic port l6-9, 16-14 
graphics tablet 7-21 
gray scales 15-16, 15-17 
green320 16-274 
green640 16-274 
greenMask 16-274 
grid values 25-45 
growBox 4-86 
growColor 25-13, 25-142 
grow image 25-75-76 
growNorBack 4-24 
growOutline 4-24 
grow?roc 4-13, 4-23, 4-73, 4-85 
grow region 25-9, 25-11 
GrowSize 4-65 

GrowWindow 25-11, 25-75-76, 
25-125 

H 

halt mechanism 18-8 
halt vector 18-6, 18-8, 18-9 
handle xxx, 12-5-6 
empty 12-8 

handleErr 12-22, 12-24, 12-27, 
12-28, 12-29, 12-30, 12-32, 
12-38, 12-40, 12-41, 12-42, 
12-43, 12-44, 12-47, B-2 
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HandToHand 12-28 
HandToPtr 12-29 
hardware interrupt enable states 
14-23 

hAxisOnly 4-53, 4-86 
hbQueueBadErr 14-70, B-2 
header section 5-3, 5-6 
HeartBeat Interrupt Handler 
14-22, 14-27, 14-49 
HeartBeat Interrupt Task 

queue 14-5, 14-27, 14-48, 
14-50, 14-52, 14-53 
helvetica 8-4, 8-51 
Hexit 9-27 
Hex2Int 9-25 
Hex2Long 9-26 
HideControl 4-10, 4-45, 4-66, 

11-11 

HideCursor 16-156 
HideDItem 6-24, 6-62, 6-81, 6-85 
HidePen 16-156, 17-9, 17-14 
HideWindow 25-11, 25-78, 25-99, 
25-113, 25-114 
high-level Event Manager 7-3 
highlighted control 4-7 
high-order word 9-28 
HiliteControl 4-7, 4-67, 6-11, 6-40, 
11-11 

HiliteMenu 13-11, 13-12, 13-56, 
13-66, 25-122, 25-123 
HiliteWindow 25-36, 25-79 
hiMouseRes 14-65 
HiWord 9-28 
HLock 12-15, 12-30 
HLockAll 12-15, 12-31 
HomeMouse 14-32 
horizontal resolution 
movement 25-45 
horScroll 4-22, 4-72, 4-85 
hot spot 16-37 
hPic 15-41, 15-48 
hPnnt 15-41, 15-48 
hrtz50or60 14-64 
Human Interface Guidelines xxviii, 
6-7, 6-8, 6-18, 6-22, 6-25, 

10-1, 13-1, 13-7, 13-9, 15-20, 
25-79 

HUnlock 12-15, 12-32 
HUnlockAll 12-15, 12-33 


I 

icon 17-3, 17-11 
note 6-74 
stop 6-86 

icon font 4-65, 4-75, 8-l6, 25-15, 
25-109 

iconimage 6-90 
iconitem 6-10, 6-88 
icon record, QuickDraw II 
Auxiliary 17-3-4, 17-11 
iconRect 6-90 
iCopies 15-14 
iCurBand 15-41, 15-48 
iCurCopy 15-41, 15-48 
iCurPage 15-41, 15-48 
idErr 12-17, 12-23, 12-31, 12-33, 
12-36, 12-39, 12-41, 12-45, 
12-47, B-2 
iDev 15-11, 15-47 
ID number 13-14, 13-16, 13-79 
idTagNtAvlErr 14-57, l4-60, 
14-70, B-2 

iPileVol 15-14, 15-15, 15-48 
iFstPage 15-14, 15-21, 15-48 
iHRes 15-11, 15-47 
iLstPage 15-14, 15-21, 15-48 
image pointer 16-13 
image width 16-44 
ImageWriter 
job dialog box 15-8-9 
style dialog box 15-6-7 
imBadInptParam 9-34, 9-38, 

9-39, 9-42, B-4 
IMBootInit 9-5 

imIllegalChar 9-8, 9-9, 9-25, 
9-26, 9-42, B-4 

imOverflow 9-8, 9-9, 9-25, 9-26, 
9-42, B-4 
IMReset 9-7 
IMShutDown 9-4, 9-6 
IMStartUp 9-4, 9-5 
IMStatus 9-7 

imStrOverf low 9-29, 9-30, 9-31, 
9-33, 9-42, B-4 
IMVersion 9-6 
inactive control 4-7, 4-8 
inactiveCtl 4-7 
inactiveHilite 4-67, 4-86 
inactive window 25-8, 25-11, 

25-24, 25-92 


inButton 6-89 
incBsyFlag 14-68 
inCheckBox 6-89 
#include statement 2-6 
indicator 4-4, 4-8, 4-83 
inDownArrow 6-89 
inEditLine 6-89 
infinity 9-40 

InflateTextBuffer l6-6l, 16-157 
InfoColor 25-20, 25-142 
information bar 25-6, 25-11, 

25-49, 25-58, 25-59, 25-63, 
25-88, 25-101, 25-102, 25-117 
inGrow ^89 
iniconitem 6-89 
InitColorTable 16-158-159 
initctl 4-25, 4-29, 4-86 
InitCursor I 6 -I 6 O 
InitMouse 14-32 
InitPalette 13-56 
InitPort 16-161 
InitTextDev 23-28 
InitTextDev 23-6 
inLongStatText 6-89 
inLongStatTextZ 6-89 
inPageDown 6-89 
inPageUp 6-89 
input 23-46 
input parameter 2-6 
input text device 23-4, 23-24, 

23 - 25 , 23 - 29 , 23-30, 23 - 34 , 
23-35, 23-40 
inRadioButton 6-89 
insertion point 6-78, 10-8, 10-10, 
10-11 

InsertMenu 13-8, 13-13, 13-57 
InsertMItem 13-13, 13-58 
InsetRect I 6 -I 62 
InsetRgn 16-163 
InstallCDA 5-18 

InsUllFont 8-14, 8-16, 8-43--44, 
10-30 

InstalINDA 5-19 
inStatText 6-89 
integer xxx, 9-1 
Integer Math string 9-1 
Integer Math string routines 1-8, 
9-4 


Index l-n 


Integer Math Tool Set 1-4, 1-7-8, 
9-1-42 

constants 9-42 
error codes 9-42 
shutdown routine 9-6 
startup routine 9-5 
status routine 9-7 
using 9-4 

version number routine 9-6 
integer value 9-1 
interface file 2-5, 2-7 
interface library 2-6 
interrupt enable states 14-23 
interrupt handler 14-5, 19-1, 19-3, 
21-27 

one-second 14-27-28 
quarter-second 14-28-29 
interrupt mode 16-34 
interrupt source l4-5 
reference numbers 14-26 
inThumb 6-89 
intrptMgr 14-67 
IntSource l4-5, 14-25-29 
Int2Dec 9-29 
Int2Hex 9-27, 9-30 
inUpArrow 6-89 
inUserltem 6-89 
invalGenNumErr 21-13, 21-15, 
21-37, B-5 

invaiidCtlVal 15-49 
InvalRect 10-36, 10-39, 25-80 
InvalRgn 25-81 
InvertArc l6-l64 
inverting 16-20 
InvertOval 16-165 
InvertPoly I 6 -I 66 
InvertRect 16-167 
InvertRgn I 6 -I 68 
I n ve rtRRect 16-169 
I/O directing routines 23-3-4 
irqActive 14-66 
irqAplTlkHi 14-66 
irqDataReg 14-66 
irqlntFlag 14-66 
irqSeriail 14-66 
irqSerial2 14-66 
irqSndData 14-66 
irqVolume 14-66 
IsDialogEvent 6-24, 6-38, 6-63-64 
convention xxxi 
italicMask 16-276 


italic type style 16-258, 17-1, 17-3 
item character 13-13 
itemColor 6-9, 6-18, 6-90 
itemDescr 6-9, 6-90 
item descriptor 6-12-16 
itemDisable 6-11, 6-53, 6-82 
itemFlag 6-9, 6-18, 6-90 
item ID 6-18, 6-55, 6 - 6 I, 13-14 
itemID 6-9, 6-90 
ItemID2FamNum 8-36, 8-45 
item line 13-13, 13-14, 13-75 
item list 13-17 

itemNotFound 6-40, 6-46, 6-50, 
6-53, 6 - 54 , 6 - 56 , 6 - 62 , 6-76, 
6-81, 6-82, 6-83, 6-84, 6-85, 
6-90, B-5 

item number 13-22 
itemRect 6-9, 6-90 
item template 6-8-9, 6-19, 6-58 
item type 6-10-11, 6-53 
itemType 6-9, 6-90 
item value 6-12-16, 6-54 
itemValue 6-9, 6-90 
iTotBands 15-41, 15-48 
iTotCopies 15-41, 15-48 
iTotPages 15-41, 15-48 
iVRes 15-11, 15-47 

J 

jcButton 7-51 
jcEvent 7-51 
jcGetMouse 7-51 
jcTickCount 7-51 
job dialog box 15-1, 15-12, 15-20 
ImageWriter 15-8-9 
job subrecord 15-9, 15-14-15, 

15- 37 

journal codes 7-20 
journaling mechanism 7-19-20 
jump table 21-6, 21-22-23 
jump table address 21-22-23 
justification 10-4, 10-6, 10-7, 
10-11, 10-36, 10-40, 10-42 

K 

kbdint 14-24, 14-66 
kerning 16-27, 16-29, 16-45-46, 

16- 58 


kemMax 16-47, 16-50 
keyboard 3-22 

keyboard equivalent 7-13, 13-7, 
13 - 61-62 

keyboard interrupts 14-27 
keyboard interrupt vector 7-15 
keyboard microcontroller 3-17, 
3-18 

key code 3-22 
keyCode 3-20, 3-28 
key-down event 6-39, 6-66, 7-3, 
7-13 

keyDownEvt 7-7, 25-120 
keyDownMask 7-11, 7-50 
keypad 7-9, 7-51 
KillControls 4-9, 4-68, 11-11, 
11-16 

KillPicture 17-5, 17-13 
KillPoly 16-40, 16-170 
kybdBuffer 14-65 
kybdDi sable 14-26, 14-67 
kybdEnable 14-26, 14-67 
kybdIntHnd 14-68 
kybdLang 14-65 
kybdMicHnd 14-68 
kybdRepDel 14-65 
kybdRepSpd 14-65 

L 

landscape mode 15-6 
langCount 14-65 
langl 14-65 
lang2 14-65 
lang3 14-65 
lang4 14-65 
langS 14-65 
lang6 14-65 
lang7 14-65 
langS 14-65 
language card 12-3 
language specification xxvii 
lastBlock 21-37 
iayoutCount 14-65 
layout 1 14-65 
lay out 2 14-65 
layouts 14-65 
lay out 4 14-66 
layouts 14-66 
layout 6 14-66 
layout? 14-66 
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layouts 14-66 
layouts 14-66 
layout 10 14-66 
lay out 11 14-66 
layoutl2 14-66 
layoutlS 14-66 
layoutl4 14-66 
layout 15 14-66 
layoutl6 14-66 
leActFlg 10-5, 10-47 
LEActivate 10-11, 10-l6 
leading 16-48, 16-62, 16-276 
leBaseHite 10-5, 10-7, 10-47 
LEBootInit 10-12 
leCarAct 10-5, 10-47 
leCaretHook 10-5, 10-9, 10-47 
leCarOn 10-5, 10-47 
leCarTime 10-5, 10-47 
LEClick 10-10, 10-17 
LECopy 10-10, 10-18 
LECut 10-10, 10-19 
LEDeactivate 10-11, 10-20 
LEDelete 10-10, 10-21 
leDestRect 10-5, 10-6-7, 10-47 
LEDispose 10-22, 10-30 
leDupStrtUpErr 10-13, 10-48, 
B-5 

LEFromScrap 10-9, 10-11, 10-23, 
20-10, C-4 

Left Arrow 10-1, 10-29 
leftFlag 4-22, 4-72, 4-85 
leftward kern 16-45-46, 16-50 
LEGetScrapLen 10-10, 10-23 
LEGetTextHand 10-10, 10-24 
LEGetTextLen 10-10, 10-25 
leHiliteHook 10-5, 10-9, 10-47 
LEIdle 10-10, 10-26 
LEInsert 10-10, 10-27 
lejust 10-5, 10-47 
leJustCenter 10-47 
leJustFill 10-47 
le Just Left 10-47 
leJustRight 10-47 
LEKey 10-10, 10-28-29 
leLength 10-5, 10-47 
leLineHandle 10-5, 10-47 
leLineHite 10-5, 10-47 
leMaxLength 10-5, 10-47 
LENew 10-10, 10-22, 10-30-31, 
10-36 


leNot ActiveErr 10-14, 10-48, 
B-5 

LEPaste 10-10, 10-32 
lePort 10-5, 10-47 
LEReset 10-15 

leResetError 10-15, 10-48, B-5 
leScrapErr 10-23, 10-48, B-5 
LEScrapHandle 10-33 
leSelEnd 10-5, 10-7, 10-47 
leSelStart 10-5, 10-7, 10-47 
LESetCaret 10-9, 10-11, 10-34 
LESetHilite 10-9, 10-11, 10-35 
LESetJust 10-11, 10-36 
LESetScrapLen 10-37 
LESetSelect 10-10, 10-38 
LESetText 10-11, 10-39 
LEShutDown 10-10, 10-14, 10-22 
LEStartUp 10-10, 10-13 
LEStatus 10-15 
LETextBox 10-11, 10-40-41 
LETextBox2 10-9, 10-11, 10-40, 
10-42-44, C-4 

LEToScrap 10-9, 10-11, 10-45, 
20-16, C-4 

LEUpdate 10-11, 10-46 
LEVersion 10-14 
leViewRect 10-5, 10-6-7, 10-47 
lightBlue320 16-274 
lightGray320 16-274 
light pen 7-21 
lilac320 16-275 
limit rectangle 4-50, 4-53 
line 16-22 
Line 16-40, 16-171 
LineEdit scrap 10-11, 10-13, 
10-18, 10-19, 10-23, 10-33, 
10-37, 10-45, 20-5 
handle 10-33 

LineEdit Tool Set 1-3, 1-8, 6-11, 
10-1-48 

constants 10-47 
data structures 10-47 
error codes 10-48 
shutdown routine 10-14 
startup routine 10-13 
status routine 10-15 
using 10-9-11 

version number routine 10-14 
LineTo 16-40, 16-103, 16-172 


list 11-1 

sorting 11-23 
ListBootInit 11-13 
list control 11-2, 11-8 
list control record 11-8-10 
creating 11-16 
listen 11-3, 11-5, 11-25 
listDraw 11-3, 11-5, 11-25 
listen 3-28 
listFrameClr 11-10, 11-26 
List Manager 1-4, 1-8, 11-1-26 
constants 11-25 
data structures 11-25-26 
shutdown routine 11-14 
startup routine 11-13 
status routine 11-15 
using 11-11 

version number routine 11-14 
listMemHeight 11-3, 11-6, 11-25 
listMemSize 11-3, 11-6, 11-25 
listNorBackClr 11-10, 11-26 
listNorTextClr 11-10, 11-26 
listPointer 11-3, 11-6, 11-25 
list record 11-2-8, 11-16 
listRect 11-3, 11-4, 11-25 
listRefCon 11-3, 11-7, 11-25 
ListReset 11-15 
listScrollClr 11-3, 11-7, 11-25 
listSelBackClr 11-10, 11-26 
listSelect 11-4, 11-5, 11-12 
listSelTextClr 11-10, 11-26 
ListShutDown 11-11, 11-14 
listSize 11-3, 11-4, 11-25 
listStart 11-3, 11-5, 11-25 
ListStartUp 11-11, 11-13 
ListStatus 11-15 
liststring 11-4, 11-5 
listType 11-3, 11-4, 11-12, 11-25 
ListVersion 11-14 
listView 11-3, 11-4, 11-25 
LoadFont 8-15, 8-46-47 
loading tool set 2-3-4 
LoadOneTool 22-13, 22-16, 22-17, 
24-3, 24-10 
LoadScrap 20-15 
LoadSysFont 8-48 
LoadTools 2-3, 24-3, 24-11-13, 
24-25 
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local coordinates 4-8, 4-50, 4-69, 
16-9, 16-16-17, 16-39, 

16-154, 16-173, 25-30, 25-31, 
25-82 

LocalToGlobal 16-39, 16-40, 

16-173 

location table 16-44, l6-49“50 
locinfo record 16-13, 16-14, 

16-138, 16-242, 16-277, 17-10 
locked movable block 12-7 
lock Err 12-36, 12-39, 12-40, 
12-41, 12-43, 12-47, B-2 
locking block, memory 12-30, 

12-31 

locSize 16-274 
london 8-4, 8-51 
LongDivide 9-34 
longint value xxx, 9-1 
LongMul 9-35 

longStatText 6-10, 6-12, 6-17, 
6-88 

longStatText2 6-10, 6-12, 6-17, 
6-88 

Long2Dec 9-31 
Long2Fix 9-32 
Long2Hex 9-33 
losAngeles 8-4, 8-51 
lost Dev 23-15, 23-47, B-4 
lost File 23-15, 23-47, B-4 
low-level Event Manager 7-3 
low-level sound routine 21-1, 21-6, 
21-35 

jump uble 21-23 
LoWord 9-36 
low-order word 9-36 

M 

MacGen 2-5 

Macintosh font record 16-41 
macro file 2-5 
mainID 12-10, 14-58 
MapPoly 16-174 
MapPt 16-175 
MapRect 16-176 
MapRgn 16-177 
marked menu item 13-80 
mask drawing 16-18 
maskHandle 16-191, 16-277 
mask Size 16-274 


master color 16-31, 16-274-275 
master color value 16-31, 16-35 
master pointer 12-5 
master scan line control byte. See 
master SCB 

master SCB 2-2, 16-127, I 6 -I 6 O, 
16-231 

master user ID 12-10-11, 12-14, 
12-15, 12-23, 12-35 
mastrIRQNotAssgnErr 21-37 
math routine 9-4 
MaxBlock 12-26, 12-34, 15-20, 

15- 22, 15-30 
maxFbrExtent 16-59-60 
maxFixed 9-42 
maxFontHeight 16-59-60 
maxFrac 9-42 

maximum content height 25-87 
maximum content width 25-87 
maxint 9-42 
maxIteraType 6-88 
maxLongint 9-42 
maxUInt 9-42 
maxULong 9-42 
maxWidth 16-59-60, I 6 - 6 I, 

16- 206, 16-276 

mChooseMsg 13-22, 13-24, 13-87 
MCOPY assembler directive 2-5 
mCustom 13-87 
mDisabled 13-87 
mDownMask 7-11, 7-50 
mDrawMItem 13-22, 13-27, 13-87 
mDrawMsg 13-22, 13-23, 13-87 
mDrawTitle 13-22, 13-26, 13-87 
mechanical specification xxvi 
member record 11-6 
disabled 11-6 
drawing 11-17 
selected 11-6, 11-12, 11-20, 
11-21, 11-22 
sorting 11-23 
memBit 8-9, 8-10, 8-50 
memDisabled 11-^, 11-25 
memErr 12-19, 12-^, 12-41, 
12-42, 12-43, 12-47, B-2 
memFlag 11-6, 11-20, 11-21, 
11-26 

memOnlyBit 8-11, 8-50 


memory 

allocating private 12-11 
allocation 12-35 
attributes 12-12, 12-37 
compaction 12-5-7, 12-15, 

12-22 

deallocation 12-23, 12-25 
expansion 12-3 
fragmentation 12-6-8 
limits 12-3 
locking 12-30, 12-31 
purging 12-39, 12-40, 12-44, 
12-45 

reallocation 12-41, 12-42 
unlocking 12-32, 12-33 
memory attributes word 12-12-13, 
12-37 

memory block 12-1, 12-5 
attributes 12-12-13, 12-37 
locking 12-30, 12-31 
purging 12-8-10, 12-13, 12-39, 

12- 40, 12-44, 12-45 
unlocking 12-32, 12-33 

memory handle 12-5 
Memory Manager 1-3, 1-9, 2-1, 

2-2, 12-1-47 
constants 12-47 
error codes 12-47 
shutdown routine 12-18 
startup routine 12-17 
status routine 12-20 
version number routine 12-19 
memory space 12-1 
memPtr 11-6, 11-26 
memSelect 11-6, 11-20, 11-21 
memSelected 11-6, 11-25 
menu 13-1 
pull-down 1-3, 13-1 
menu bar 13-4-5. See also system 
menu bar 
window 13-5 

menu bar color 13-18, 13-42^3, 

13- 69-70 

menu bar record 13-17-18 
MenuBootInit 13-29 
menu color 13-17 
menu definition procedure 
13-21-28 

menuFlag 13-19, 13-20, 13-21, 
13 - 23 , 13-88 
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MenuGlobal 13-59-60 
menu global mask 13-59-60 
menu height 13-33 
menuHeight 13-19, 13-21, 13-25, 
13-88 

menu help 13-60 
menu ID 13-14, 13-16 
menuID 13-19, 13-21, 13-88 
menu item 13-6, 13-50 
blinking 13-76 
checking 13-34 
dimming 13-6, 13-38, 13-60 
disabling 13-6, 13-38 
marking 13-51, 13-80 
text style 13-52, 13-83 
underlining 13-15-16, 13-77 
menu item ID 8-31, 8-45, 13-14, 
13-79 

menu item line 13-13, 13-75 
menu item number 13-22 
MenuKey 13-6, 13-11, 13-61-62, 
25-120 

menu line 13-13, 13-14 
MenuLine 5-8 
menu list 13-13-15, 13-17 
menuList 13-17, 13-18 
Menu Manager 1-3, 1-9-10, 5-20, 
13-1-88 

constants 13-87 
data structures 13-88 
port 13-46 

shutdown routine 13-31 
startup routine 13-30 
status routine 13-32 
using 13-7-13 

version number routine 13-31 
menu messages 13-22 
MenuNewRes 13-63 
menu position 13-17 
menuProc 13-19, 13-20, 13-21, 
13-88 

menu record 13-19-20, 13-21, 
13-48, 13-88 

MenuRefresh 13-13, 13-64-65 
MenuReset 13-32 
MenuSelect 13-12, 13-66, 25-11, 
25-120, 25-121 
MenuShutDown 13-7, 13-31 
MenuStartUp 13-7, 13-8, 13-30, 
13-68 


MenuStatus 13-32 
menu title 13-47, 13-53, 13-54, 
13-74 

MenuVersion 13-31 
menu width 13-33 
menuWidth 13-19, 13-21, 13-25, 
13-88 

message 7-6, 7-8, 7-43, 7-51 
MessageCenter 24-3, 24-14-15 
action codes 24-15 
message type 24-14 
messNotFoundErr 24-14, 24-26, 
B-2 

mGetMItemID 13-22, 13-87 
minFixed 9-42 
minFrac 9-42 

minimum blink interval 10-26 
minimum version 2-4 
minimum version number 24-10, 
24-11 

minint 9-42 
minipalette 16-33, 16-35 
minItemType 6-88 
minLongint 9-42 
minvis 13-87 
Miscellaneous Tool Set 1-3, 
1-10-11, 2-1, 14-1-70 
constants 14-64-68 
data structures 14-69 
error codes 14-70 
shutdown routine 14-7 
startup routine 14-6 
status routine 14-8 
using 14-4-5 

version number routine l4-7 
missing character 16-48-49 
missingDriver 15-26, 15-49, B-5 
missing symbol 16-48-50 
mItemDisable 13-78 
mItemEnable 13-78 
MMBootInit 12-16 
MMReset 12-19 

MMShutDown 12-14, 12-18, 12-23 
MMStartUp 2-1, 12-10, 12-14, 

12-17, 12-18 
MMStatus 12-20 
MMVersion 12-19 
ModalDialog 6-24, 6-65-66 
ModalDialog2 6-67 
modal dialog box 6-5 


mode 16-191, 16-277 
modeBIC 16-19, l6-20, 16-235, 
16-275 

modeCopy 16-19, 16-20, 16-235, 
16-275 

modeForeBIC l6-30, 16-260, 
16-275 

modeForeCopy 16-30, 16-260, 
16-275 

modeForeOR 16-30, l6-260, 

16-275 

modeForeXOR 16-30, l6-260, 
16-275 

modeless dialog box 6-5, 6-63 
modeOR 16-19, 16-20, 1^235, 
16-275 

modeXOR 16-19, l6-20, 16-235, 
16-275 

modifiers 7-6, 7-8, 7-43, 7-51 
modifier key 7-3 
monaco 8-4, 8-51 
mouse button 4-46 
mouse Clamps 14-21, 14-66 
mouse clamp value 2-2, 7-27 
mouse-down event 4-10, 5-26, 

6- 39, 6-64, 6-66, 7-3, 7-8, 

7- 13, 25-11, 25-48-49, 25-92, 
25-127, 25-129-130 

mouseDownEvt 7-7, 7-50, 25-120, 
25-121 

mouse interrupt status 14-35 
mouseIntHnd 14-68 
mouse location 16-37 
mouse mode 14-36 
mouseOff 14-36, 14-67 
mouseOffVI 14-36, 14-67 
mouse routine 14-5 
mouseSlot 14-66 
mouse-up event 7-3, 7-13 
mouseUpEvt 7-7, 7-50 
Move 16-40, 16-178 
MoveControl 4-10, 4-69, 11-11 
moveCtl 4-25, 4-39, 4-86 
moveintrpt 14-36, 14-67 
moveIntrptVI 14-36, 14-67 
movement constraint values 4-53 
MovePortTo 16-179 
MoveTo 16-40, 16-180, 25-22 
Move Window 25-44, 25-82, 25-138 
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mSelected 13-87 
msgPtrVctr 14-68 
mSizeMsg 13-22, 13-25, 13-87 
mstrIRQNotAssgnErr B-3 
MTBootInit 14-6 
MTReset 14-8 
MTShutDown 14-4, 14-7 
MTStartUp 2-1, 14-4, l4-6 
MTStatus 14-8 
MTVersion 14-7 
Multiply 9-37 
Munger 14-5, 14-45-47 
mUpMask 7-11, 7-50 
mvEscape 24-26 
mvReturn 24-26 
mXor 13-87 

N 

NaN 9-40, 9-41 
native mode 1-2, 1-4 
NDA header section 5-19 
newBarColor 13-70 
NewControI 4-9, 4-24, 4-70-73, 
11-11, 25-68 
new desk accessory 5-1 
action codes 5-7 
total number installed 5-17 
NewDItem 6-23, 6-68-69 
NewHandle 12-15, 12-35-37, 

15- 19 

newlnvertColor 13-70 
newItemFailed 6-57, 6-69, 6-90, 
B-5 

NewList 11-19 

NewMenu 13-8, 13-16, 13-21, 
13-67 

NewMenuBar 13-68 
NewModalDialog 6-7, 6-23, 
6-70-71 

NewModelessDialog 6-7, 6-23, 
6-72-73 

newOut Color 13-70 
NewRgn 16-40, 16-74, 16-113, 

16- 153, 16-181 
newValue 4-25, 4-37, 4-86 
NewWindow 25-11, 25-16, 25-21, 

25-25, 25-38, 25-83-88 
NewWindow parameter list 25-142 
newYork 8-4, 8-51 


NextMember 11-20 
nextWavePtr 21-17, 21-37 
noConstraint 4-53, 4-86 
noDevice 23-15, 23-47, B-4 
noDevParamErr 14-32, 14-70, B-2 
noDisplay 22-22, 22-32 
noDOCFndErr 21-8, 21-24, 21-28, 
21-37, B-3 
noEcho 23-46 
noFile 23-15, 23-47, B-4 
noHilite 4-67, 4-86 
nonreentrant code 19-1 
nonspecial memory 12-3 
noPart 4-86 

noPrintRecord 15-49, B-5 
normal memory 12-3 
no Room 23-15, 23-47, B-4 
noSAppinitErr 21-15, 21-37, B-3 
noSelect 22-22, 22-32 
noSigTaskErr 14-48, 14-70, B-2 
notBaseBit 8-12, 8-50 
notBIC 16-19, 16-20, 16-235, 
16-275 

notClosed 23-15, 23-47, B-4 
notCopy 16-19, 16-20, 16-235, 
16-275 

not Disk Bit 8-9, 8-50 
note alert 6-6 
NoteAlert 6-24, 6-74 
note icon 6-74 
notEmptyErr 12-41, 12-42, 

12-47, B-2 

NotEmptyRect 16-182 
notEqualChunkiness 16-190, 
16-197, 16-278, B-3 
Note Sequencer 1-4, 21-1 
noteSynth 21-37 
Note Synthesizer 1-4, 21-1 
noteSynthMode 21-36 
notForeBIC 16-30, 16-260, 

16-275 

notForeCOPY l6-30, l6-260, 
16-275 

notForeOR l6-30, l6-260, 16-275 
notForeXOR 16-30, l6-260, 

16-275 

notFoundBit 8-12, 8-50 
notImplemented 16-278 
not Initialized 16-278, B-3 


notModalDialog 6-65, 6-67, 

6-90, B-5 

not Open 23-16, 23-47, B-4 
not OR 16-19, 16-20, 16-235, 
16-275 

notSysWindow 5-14, 5-30, B-3 
notXOR 16-19, 16-20, 16-235, 

16- 275 

noUnderMItem 13-78, 13-87 
nullEvt 7-7, 7-50, 25-119 
number of copies 15-8 
numeric spacing 16-226 
numOfItems 13-19, 13-20, 13-88 

O 

object module format xxvii 
Obscure Cursor 16-182 
offseToMF 16-43, 16-276 
offset point 4-50 
OffsetPoly 16-183 
OffsetRect 16-184 
OffsetRgn 16-185 
offset/width table 16-44, 16-50-51 
ok 6-89 

OK button 6-4, 6-5, 6-18, 6-58 
ok Default 6-89 
oneSecHnd 14-68 
oneSecInt 14-24, 14-66 
one-second interrupt handler 
14-27-28 

Open File dialog box 22-3, 22-4, 
22-21, 22-25-26 
OpenNDA 5-6, 5-20, 25-122 
OpenPicture 15-38, 17-5, 17-9, 

17- 14 

OpenPoly 16-40, 16-186 
OpenPort 16-39, I 6 -I 6 I, 16-187, 
25-42 

OpenRgn 16-40, 16-74, 16-187 
operating system xxviii 
optionKey 7-9, 7-51 
Option-Left Arrow 10-1, 10-29 
Option-Right Arrow 10-1, 10-29 
orange320 16-275 
origin 4-8, I 6 -I 6 , 25-29-31, 

25 - 52 , 25-95, 25-96, 25-104, 
25-116 

origin mask 25-104 
oscillator register 21-5 
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oscillator table 21-22, 21-23 
oscillator-to-generator translation 
table 21-5 
oscTable 21-36 
oSecDi sable 14-24, 14-67 
oSecEnable 14-24, 14-67 
OSEventAvail 7-42 
osVector 14-68 
otherIntHnd 14-68 
outlineMask 16-276 
outline type style 16-258, 17-1, 
17-3 

outOfMemErr 14-56, 14-70, B-2 
output 23-46 
output parameter 2-6 
output sample rate 21-17 
output text device 23-4, 23-26, 
23-27, 23-37, 23-38, 23-41, 
23-42, 23-43, 23-44, 23-45 
oval 16-23, 16-89, 16-95, 16-102, 
16-165, 16-189 

P 

packagelErr 14-55, 14-70, B-1 
package2Err 14-55, 14-70, B-1 
packageSErr 14-55, 14-70, B-1 
package4Err 14-55, 14-70, B-1 
packageSErr 14-55, 14-70, B-1 
package6Err 14-55, 14-70, B-1 
package7Err 14-55, 14-70, B-1 
packageSErr 14-55, 14-70, B-1 
packageSErr 14-56, 14-70, B-1 
pack age lOErr 14-56, 14-70, B-2 
packagellErr 14-56, 14-70, B-2 
package 12Err 14-56, 14-70, B-2 
PackBytes 14-5, 14-39-41, 14-42 
page 4-5 

page-aligned memory block 2-2, 
12-12, 12-13 
PageDown 4-86 
page range 15-8, 15-38 
page rectangle 15-11 
page region 25-62, 25-105 
page setup 15-1 
PageUp 4-86 
paging region 4-5, 4-8 
PaintArc 16-188 
painting 16-20 
PaintOval 16-189 


PaintPixels 16-190-191 
PaintPixels parameter block 
16-191, 16-277 
PaintPoly 16-192 
PaintRect 16-193 
PaintRgn 16-194 
PaintRRect 16-195 
palette 16-32 

standard in 320 mode 16-35 
standard in 640 mode 16-36 
papConnNotOpen 15-36, 15-42, 
15-49, B-5 
paper source 15-8 
paperType 15-12, 15-13, 15-48 
papReadWriteErr 15-36, 15-42, 
15-49, B-5 
parameter 

Battery RAM reference 
numbers 14-12 
definition xxix 
DragRect 4-50-53 
GetAddr reference numbers 

14-20 
input 2-6 
length XXX 
NewControl 4-71-73 
output 2-6 
passing 2-6 
pseudo-type xxx 
paramLenErr 25-83, 25-144, B-4 
paramLength 25-84, 25-142 
paraml 6-90 
param2 6-90 
ParamText 6-24, 6-75 
part code 4-8, 4-57, 4-67, 4-81, 
4-82, 4-83, 4-84, 6-67 
Pascal device driver 23-3 
Pascal string 5-3, 16-26 
pascalType 23-46 
paste 5-30 
pasteAction 5-7, 5-30 
Paste command 6-44, 20-1, 20-6 
patsize 16-274 
pattern 16-265 

pdosBlkOErr 14-55, 14-70, B-1 
pdosFCBErr 14-55, 14-70, B-1 
pdosIntShdwErr 14-55, 14-70, 
B-1 

pdosUnClmdIntErr 14-55, 14-70, 
B-1 


pdosVCBErr 14-55, 14-70, B-1 
pen displacement 16-29, 16-56, 
16-70, 16-77, 16-267, 16-270 
pen level 16-156, 16-265 
pen location 16-17, 16-18, 16-22, 
16-26, 16-40, 16-80, 16-81, 
16-82, 16-83, 16-128, 16-178, 
16-180, 16-196 
pen mask 16-129, 16-233 
pen mode 16-19-20, 16-22, 
16-130, 16-234-235, 16-275 
PenNormal 16-196 
pen pattern 16-18-19, 16-131, 
16-236, 16-252 

pen size 16-18, 16-22, 16-132, 
16-237 

pen state 16-133, 16-196, 16-238 
pen state record 16-238 
PenState record 16-278 
periwinkleBlue 16-274 
pFileName 15-14, 15-15, 15-48 
PicComment 17-5, 17-15 

picitem 6-10, 6-12, 6-88 

picSave 16-134, 16-239, 

16-277, 17-14 
picScrap 20-4, 20-19 
picture 16-25, 17-1, 17-2-3 
picture definition 17-14 
pIdleProc 15-14, 15-15, 15-24, 

15- 48 

pinning 9-3 

PinRect 25-89-90 

pixel 16-10-11, 16-135, 16-197, 

16 - 200, 16-201 
background 16-28, 16-30 
chunky 16-31 
foreground 16-27, 16-30 
region 16-190 

pixel image 2 -2, l6-9, 16-12-14, 
16-48, 17-10 

place-holding character 5-8 
plane 25-8 
PMBootInit 15-25 
PMReset 15-28 
PMShutDown 15-19, 15-27 
PMStartUp 15-19, 15-26 
PMStatus 15-28 
PMVersion 15-27 
pnStateSize 16-274 
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point XXX, 8-4, 16-11-12, 

16-21-22, 16-40, 16-68, 

16-85, 16-135, 16-154, 

16-175, 16-199, 16-200, 

16-201, 16-207, 16-268, 25-89 
POINTER XXX 

pointing device 7-21-25, 7-27, 
7-34, 14-5 

polling, Apple Desktop Bus 3-3 
polyAlreadyOpen 16-186, 

16-278, B-3 

polygon 16-24-25, 16-40, 16-72, 
16-90, 16-96, 16-103, 16-166, 
16-170, 16-174, 16-183, 

16-186, 16-192 

polyNotOpen 16-72, 16-278, B-3 
polySave 16-136, 16-240, 16-277 
polyTooBig 16-278, B-3 
plAddLine 14-64 
plBaud 14-64 
plBuffer 14-64 
plDCDHndShk 14-64 
plDelLine 14-64 
plDSRHndShk 14-64 
plDtstpBits 14-64 
plEcho 14-64 
plLineLnth 14-64 
plParity 14-64 
plPrntModem 14-64 
plXnfHndShk 14-64 
port. See GrafPort 
port driver 15-24, 15-43 
portNotOn 15-30, 15-31, 15-36, 

15- 39, 15-40, 15-42, 15-49, 

B-5 

portrait mode 15-6 

port rectangle 16-14-15, 16-16, 

16- 139, 16-179, 16-208, 

16-232, 16-243, 16-244, 

25-17, 25-77, 25-82, 25-115 

portRect field 16-14, 16-15 
portSCB 16-13, 16-277 
port Size 16-274 
posCtl 4-25, 4-86 
PosMouse 14-33 
PostEvent 7-14, 7A5-44 
pPrPort 15-41, 15-48 
PPToPort 16-197-198 
prAbort 15-20, 15-22, 15-34, 15- 
44, 15-47 


PrChoosePr inter 15-20, 15-22, 
15-29 

PrCloseDoc 15-20, 15-21, 15-30, 
15-36, 15-40 

PrClosePage 15-20, 15-21, 15-31, 
15-38 

PrDefault 15-19, 15-22, 15-46 
PrDriverVer 15-33 
PrError 15-22, 15-30, 15-34 
prestyled fonts 8-5-6, 16-43 
prinfo 15-10, 15-11, 15-47 
Print 15-1 

printer driver 15-1, 15-23, 15-33 
printer effects choice 15-6 
printer error code 15-34, 15-44, 
15-49 

printer information subrecord 
15-11 

printer names dialog box 15-5 
printer paper 15-5 
printer status record 15-41 
printer style subrecord 15-12-13 
printing 

color 15-15-18 
draft 15-14-15, 15-23, 15-37 
spool 15-14-15, 15-23, 15-37, 
15-40 

printing loop 15-20, 15-34 
Print Manager 1-4, 1-11, 15-1-50 
constants 15-47 
data structures 15-47-48 
error codes 15-49 
shutdown routine 15-27 
startup routine 15-26 
status routine 15-28 
using 15-19-22 
version number routine 15-27 
print record 15-9-15, 15-19, 

15-32, 15-46 

private memory 12-11, 12-14 
private scrap 20-5-6 
prjob 15-10, 15-47 
PrJobDialog 15-20, 15-21, 15-22, 
15-35, 15-46 
ProDOS 5-4 

ProDOS 16 xxviii, 5-7, 5-18, 5-19, 
12-1, 12-14 
proDOSVctr 14-68 
PrOpenDoc 15-20, 15-21, 15-22, 
15-36-37, 15-40 


PrOpenPage 15-20, 15-21, 15-22, 

15-38-39 

proportionally spaced font 16-226 
proportional scroll bars 25-10 
PrPicFile 15-20, 15-22, 15-30, 

15-40-41 
PrPixelMap 15-42 
PrPortVer 15-43 
PrSetError 15-21, 15-22, 15-22, 

15-44 

prStl 15-10, 15-12, 15-47 
PrStIDialog 15-20, 15-21, 15-22, 

15-45, 15-46 

PrValidate 15-19, 15-21, 15-22, 

15- 35, 15-45, 15-46 
pseudorandom numbers 16-202 
pseudo-type xxx 
prVersion 15-10, 15-47 
psInstDiskErr 14-56, 14-70, B-2 
psPnMask 16-238, 16-278 
psPnMode 16-238, 16-278 
psPnPat 16-238, 16-278 
psPnSize 16-238, 16-278 
PtInRect 16-200 

PtInRgn 16-201 

ptrToDestLocInfo 16-191, 16-277 
ptrToDestPoint 16-191, 16-277 
PtrToHand 12-38 
ptrToPixImage 16-13, 16-277 
ptrToSourceLocInfo 16-191, 

16- 277 

ptrToSourceRect 16-191, 16-277 
Pt2Rect 16-199 
p2AddLine 14-64 
p2Baud 14-64 
p2Buffer 14-64 
p2DCDHndShk 14-64 
p2DelLine 14-64 
p2DSRHndShk 14-64 
p2DtStpBits 14-64 
p2Echo 14-64 
p2LineLnth 14-64 
p2 Parity 14-64 
p2PrntModem 14-64 
p2XnfHndShk 14-64 
public scrap type 20-4 
pull-down menu 1-3, 13-1 
purgeable block 12-39, 12-40 
PurgeAll 12-11, 12-39 
purgeBit 8-9, 8-10, 8-50 
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purge block 12-8 

purge Err 12-39, 12-40, 12-47, 

B-2 

PurgeHandle 12-40 
purge level 12-9, 12-15, 12-44, 
12-45, 24-25 
pu r pi e 3 2 0 16-274 
PutScrap 20-5, 20-6, 20-11, 20-16, 
20-18 

Q 

QDAuxBootInit 17-6 
QDAuxReset 17-8 
QDAuxShutDown 17-5, 17-7 
QDAuxStartUp 17-5, 17-6 
QDAuxStatus 17-8 
QDAuxVersion 17-7 
QDBootInit 16-63 
QDReset 16-67 
QDShutDown 16-39, 16-66 
QDStartUp 2-2, 16-39, 16-59, 

16-61, 16-64-45, 16-275 
QDStatus 16-67 
QDVersion 1646 
qSecDi sable 14-26, 14-67 
qSecEnable 14-26, 1447 
qSecIntHnd 14-68 
quarter-second interrupt 
handler 14-28-29 
quartSecInt 14-24, 14-66 
queueDmgdErr 14-48, 14-52, 

14-70, B-2 

QuickDraw II 1-3, 1-11-14, 2-2, 
16-1-278 

constants 16-274-276 
data structures 16-276-278 
error codes 16-278 
shutdown routine 1646 
startup routine 1644-65 
status routine 1647 
using 16-39-40 
version number routine 1646 
QuickDraw II Auxiliary 1-4, 1-14, 
2-4, 8-5, 8-14, 10-44, 13-83, 
16-258, 17-1-16, C-6 
shutdr A^n routine 17-7 
staitup routine 17-6 
status routine 17-8 
using 17-5 

version number routine 17-7 


R 

radio button 4-4, 4-10, 4-18 
control record 4-18-20 
radioButton 4-86 
radioltem 6-10, 6-88 

radio?roc 4-13, 4-19, 4-73, 4-85 
radNor 4-20, 4-88 
radReserved 4-20, 4-88 
radSel 4-20, 4-88 
radTitle 4-20, 4-88 
ramBased 23-46 
RAM-based device driver 23-1, 
23-4 

RAM-based tool set 24-3 
RAM tool set 1-1, 2-3 
Random 16-202, 16-246 
random number generator 16-246 
range mode 11-12 
rcADBAddr 3-29 
rcLayoutOrLang 3-29 
rcRepeatDelay 3-29 
rdMaxRani 14-65 
rdMinRam 14-65 
ReadAbs 3-16 
readADBError 3-17, 3-28 
ReadASCIITime 14-4, 14-16 
readAvailCharSet 3-17, 3-28 
readAvailLayout 3-17, 3-28 
ReadBParam 14-4, 14-13 
ReadBRam 14-4, 14-10 
ReadChar 23-7, 23-29, 23-30, 
23-40 

readConfig 3-17, 3-28 
ReadConfigRec 3-29 
ReadKeyMicroData 3-17 
ReadKeyMicroMemory 3-18 
ReadLine 23-30-31 
readMicroMem 3-28 
readModes 3-17, 3-28 
ReadMouse 14-34 
read next 21-23, 21-33 
readNext 21-23, 21-36 
Read RAM 21-23, 21-31 
readRAM 21-23, 21-36 
ReadRamBlock 21-24 
Read Register 21-23, 21-29 
readRegister 21-23, 21-36 
ReadTimeHex 14-4, 14-14 
readVersionNum 3-17, 3-28 


real font 8-7 

reallocation of memory 12-43, 
12-44 

ReAllocHandle 12-15, 12-41 
realOnlyBit 8-11, 8-50 
recCtl 4-25, 4-39, 4-40 
recSize 4-25, 4-86 
RECT XXX, 16-22 
rectangle 16-22-23, 16-40, 16-86, 
6-91, 16-97, 16-104, 16-162, 
16-167, 16-176, 16-182, 

16-184, 16-193, 16-203, 

16-204, 16-208, 16-209, 

16-247, 16-248, 16-271, 

25-80, 25-89, 25-131 
RectInRgn 16-203 
RectRgn 16-204 
red32 0 16-275 
red64 0 16-274 
redMask 16-274 
redraw routine 13-64-65 
reduction 15-12, 15-13, 15-48 
reentrant code 18-10, 19-1, 19-3 
RefreshDesktop 25-91, 25-135 
region 16-25, l6-40, 16-74, 16-75, 
16-78, 16-79, 16-84, 16-87, 
16-92, 16-98, 16-105, 16-163, 
16-168, 16-171, 16-172, 

16-177, 16-181, 16-185, 

16-187, 16-194, 16-203, 

16-204, 16-210, 16-218, 

16-223, 16-248, 16-272, 

16-273, 25-81, 25-132 
register 2-7 

RemoveDItem 6-24, 6-76 
repeat delay 7-3 
repeat speed 7-3 
reply record 22-24, 22-31, 22-32 
reserved memory 12-3 
resetADB 3-21, 3-28 
ResetAlertStage 6-76 
resetKbd 3-20, 3-28 
ResetMember 11-21 
resetSys 3-20, 3-28 
resolution. See screen resolution 
RestAll 5-21 

RestoreBufDims 16-58, 16-61, 
16-205 

RestoreHandle 12-15, 12-42 
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RestoreTextState 24-3, 24-16 
RestScrn 5-21 
resultID 8-10, 8-51 
resultStats 8-10, 8-51 
Return key 4-14, 6-5, 6-11, 6-25, 
6-37 

rfFamNum 16-142, 16-278 
rfFamStyle 16-142, 16-278 
rfFBRExtent 16-142, 16-278 
rfFontHandle 16-142, 16-278 
rfNamePtr 16-142, 16-278 
rfSize 16-142, 16-278 
rgnAlreadyOpen 16-187, 16-278, 
B-3 

rgnFull 16-278, B-3 
rgnNotOpen 16-74, 16-278, B-3 
rgnScanOverf low 16-278, B-3 
rgnSave 16-140, 16-249 
Right Arrow 10-1, 10-29 
right Flag 4-22, 4-72, 4-85 
right scroll bar 25-6 
ringBuffOFlo 23-16, 23-47, B-4 
ROM font 8-1, 8-19, 16-141 
ROM font record 16-142, 16-278 
ROM tool set 1-1, 2-3 
rounded-corner rectangle 16-23, 
16-93, 16-99, 16-106, 16-169, 
16-195 

rounded result 9-3 
routine number D-1-9 
rPage 15-11, 15-38, 15-48 
rPaper 15-10, 15-11, 15-47 
runAction 5-7, 5-8, 5-30 

S 

SANEBootInit 18-11 
SANEDecStr8l6 18-2, 18-15 
SANE direct page 18-6, 18-9 
SANEElems8l6 18-2, 18-15 
SANEFP816 18-2, 18-15 
SANEReset 18-14 
SANEShutDown 18-3, 18-13 
SANESurtUp 18-3, 18-12 
SANEStatus 18-14 


SANE Tool Set xxviii, 1-4, 1-14, 
18-1-15 

shutdown routine 18-13 
startup routine 18-12 
status routine 18-14 
using 18-3-6 

version number routine 18-13 
SANEVersion 18-13 
sanFran 8-4, 8-51 
SaveAll 5-22 

SaveBufDims 16-58, l6-6l, 

16-206 

SaveBufDims record 16-206 
Save File dialog box 22-3, 22-4, 
22-8, 22-27, 22-30 
SaveScrn 5-22 
SaveTextSute 24-3, 24-16, 
24-17-18 

SaveTextState record 24-18 
scADBAddr 3-29 
sCalcRgns 25-25 
ScalePt 16-207 
ScaleRec 3-29 

scale record 3-23, 3-24, 3-29 
scaling 8-7, 8-23, 8-44 
scan line control byte (SCB) 2-2, 
16-13, 16-34, 16-127, 16-143, 
16-145, 16-211, 16-213, 
16-228, 16-231, 16-250, 
16-275 

scanLineInt 14-24, 14-66 
scan line interrupt 16-230 
SCB. See scan line control byte 
scbColorMode 16-275 
scbFill 16-275 
scbinterrupt 16-275 
scbReserved 16-275 
sccIntFlag 14-66 
sccIntHnd 14-67 
SchAddTask 19-3, 19-7 
SchBootInit 19-4 
Scheduler 1-4, 1-14, 5-3, 19-1-8 
shutdown routine 19-5 
startup routine 19-4 
status routine 19-6 
using 19-2-3 

version number routine 19-5 
Scheduler queue 19-3, 19-7 


SchFlush 19-3, 19-8 
SchReset 19-6 
SchShutDown 19-2, 19-5 
SchStartUp 19-2, 19-4 
SchStatus 19-6 
SchVersion 19-5 
scLayoutOrLang 3-29 
scLnDisable 14-26, 14-67 
scLnEnable 14-26, 14-67 
scLnIntHnd 14-67 
scrap. See also desk scrap 
Line Ed it 20-5 
private 20-5-6 
ScrapBootInit 20-7 
scrap count 20-5, 20-11 
Scrap Manager 1-3, 1-15, 10-45, 
20-1-19 

constants 20-19 
error codes 20-19 
shutdown routine 20-8 
startup routine 20-7 
status routine 20-9 
using 20-4-5 

version number routine 20-8 
ScrapReset 20-9 
ScrapShutDown 20-4, 20-8 
ScrapStartUp 20-4, 20-7 
ScrapStatus 20-9 
ScrapVersion 20-8 
screen hole 5-4, 5-21, 5-22 
screen memory 16-71 
screenReserved 16-64, 16-278, 
B-3 

screen resolution 13-63, 15-15, 
25-135 

screenTable 16-107 
scRepeatDelay 3-29 
scroll bar. See also dialog scroll bar 
4-5-7, 4-10, 4-20, 25-9-10, 
25-62, 25-87, 25-88, 25-95, 
25-105, 25-106 
bottom 25-6 
control record. 4-20-22 
right 25-6 

scrollBarltem 6-10, 6-12, 6-88 
scrollLineDown 6-15, 6-88 
scrollLineUp 6-15, 6-88 
scrollPageDown 6-15, 6-88 
scrollPageUp 6-15, 6-88 
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scrollProc 4-13i 4-21, 4-73, 

4-85 

ScrollRect 16-39, 16-208 
scrollThumb 6-15, 6-88 
SDivide 9-38 
SectRect 16-209 
SectRgn 16-210 

segLoaderlErr 14-55, 14-70, B-1 
segLoader2Err 14-56, 14-70, B-2 
selection mode 11-12 
selection range 6-78, 10-4, 

10-7-8, 10-9, 10-11 
SelectIText 6-77-78 
SelectMember 11-22 
selectOnlyOne 11-25 
SelectWindow 25-11, 25-36, 25-79, 
25-92, 25-124, 25-126 
SellText 6-24 
SendBehind 25-93 
Sendinfo 3-4, 3-5, 3-6, 3-19-22, 
7-24, 7-25 

Serial Communications Controller 
CSCC) interrupt flag 14-21 
ServeMouse 14-34, 14-35 
SetAbsClamp 7-27, 14-5, 14-37 
SetAbsScale 3-15, 3-23 
SetAllSCBs 16-211 
SetArcRot 16-212 
SetBackColor 16-55, 16-213 
SetBackPat 16-214 
SetBarColors 13-41, 13-67, 
13-69-70 

SetBufDims 16-58-59, 

16-215-216 

SetCharExtra 16-51, 16-55, 16-217 
SetClip 6-7, 16-40, 16-218 
SetClipHandle 16-219 
SetColorEntry 16-220 
SetColorTable 16-221 
setConfig 3-20, 3-28 
SetConfigRec 3-29 
SetContentDraw 25-94 
SetContentOrigin 25-95 
SetContentOrigin2 25-96 
SetCtlAction 4-74, 11-11 
SetCtllcons 4-11, 4-75 
SetCtlParams 4-6, 4-76, 11-11 
SetCtlRefCon 4-77 
SetCtlTitle 4-78, 11-11 


\ 

SetCtlValue 4-10, 4-79, 4-84, 
11-11 

SetCursor 16-222 
SetDAFont 6-24, 6-79 
SetDAStrPtr 5-23-25 
SetDataSize 25-97 
SetDefButton 6-80 
SetDefProc 25-98 
SetDeskPat 25-41, 25-139 
SetDesktop 25-41, 25-139 
SetDItemBox 6-81 
SetDItemType 6-82 
SetDItemValue 6-12, 6-83 
SetEmptyRgn 16-223 
SetErrGlobals 23-5, 23-32 
SetErrorDevice 23-6, 23-33 
SetEventMask 7-45 
SetFont 8-l6, 16-224 
SetFontFlags 16-56, 16-225-226 
SetFontID 8-l6, 16-227 
SetForeColor 16-55, 16-228 
SetFrameColor 25-20, 25-99-100 
SetGrafProcs 16-229 
SetHandleSize 12-43 
SetHeartBeat 7-23, 14-48-51 
SetInfoDraw 25-101 
SetInfoRefCon 25-102 
SetInGlobals 23-5, 23-34 
SetInputDevice 23-5, 23-35-36 
SetIntUse 16-230 
SetIText 6-23, 6-84 
SetMasterSCB 16-231 
SetMaxGrow 25-103 
SetMenuBar 13-71 
SetMenuFlag 13-72 
SetMenuID 13-16, 13-73 
SetMenuTitle 13-13, 13-74 
SetMItem 13-13, 13-75 
SetMItemBlink 13-13, 13-76 
SetMItemFlag 13-15, 13-77-78 
SetMItemID 13-16, 13-79 
SetMItemMark 13-6, 13-80 
SetMItemName 13-81 
SetMItemStyle 13-6 
set Modes 3-20, 3-28 
SetMouse 14-34, 14-36 
SetMTitleStart 13-82 
SetMTitleWidth 13-83 


SetOrigin 10-11, 15-22, 16-39, 
16-232, 25-21, 25-31, 25-116 
SetOriginMask 25-104 
SetOutGlobals 23-5, 23-37 
SetOutputDevice 23-6, 23-38 
SetPage 25-105 
setParams 4-25, 4-38, 4-86 
SetPenMask 16-233 
SetPenMode 16-40, 16-234-235, 
16-259 

SetPenPat 16-40, 16-236 
SetPenSize 16-40, 16-237 
SetPenState 16-238 
SetPicSave 16-239 
SetPolySave 16-240 
SetPort 16-39, 16-241, 25-116 
SetPortLoc 16-242 
SetPortRect 16-243 
SetPortSize 16-244 
SetPt 16-245 
SetPurge 12-15, 12-44 
SetPurgeAll 12-15, 12-45 
SetPurgeStat 8-15, 8-49 
SetRandSeed 16-202, 16-246 
SetRect 16-247 
SetRectRgn 16-248 
SetRgnSave 16-249 
SetScrapPath 20-17 
SetScrolI 25-106 
SetSolidBackPat 16-251 
SetSolidPenPat 16-252 
SetSoundMIRQV 21-25 
SetSoundVolume 21-26 
SetSpaceExtra 16-51, 16-55, 
16-253 

SetStdProcs 16-254 
SetSwitch 7-46 
SetSysBar 13-8, 13-86 
SetSysField 16-255 
SetSysFont 8-19, 8-39, 16-256 
SetSysWindow 25-107 
SetTextFace 16-56, 16-257-258 
SetTextMode 16-55, 16-259-260 
SetTextSize 16-261 
SetTSPtr 24-3, 24-19, A-6 
SetUserField 16-262 
SetUserSoundIRQV 21-27 
SetVector 7-23, 14-5, 14-26, 
14-53, 14-61-62, 14-63 
SetVisHandle 16-263 
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SetVisRgn 16-264 
SetWAP 24-3, 24-20. A-7, A-8 
SetWFrame 25-108 
SetWindowIcons 25-15, 25-109 
SetWRefCon 25-28, 25-110 
SetWTitle 25-111 
SetZoomRect 25-112 
SFAliCaps 22-20 
SFBootInit 22-15 
SFGetFile 22-14, 22-21-24 
SFPGetFile 22-14, 22-25-26 
SFPPutFile 22-14, 22-27-29 
SFPutFile 22-14, 22-30-31 
SFReset 22-18 

SFShutDown 22-13, 22-17, 22-19 
SFStartUp 22-13, 22-16, 22-19 
SFStatus 22-19 
SFVersion 22-18 
shadowMask 16-276 
shadow type style 16-258, 17-1, 
17-3 

shaston 8-4, 8-51 
shftCpsLCas 14-65 
Shift-Apple-Left Arrow 10-2, 10-29 
Shift-Apple-Right Arrow 10-2, 

10-29 

shift Key 7-9, 7-10, 7-51 
Shift-Left Arrow 10-1, 10-29 
Shift-Option-Left Arrow 10-1, 10-2, 
10-29 

Shift-Option-Right Arrow 10-1, 

10- 2, 10-29 

Shift-Right Arrow 10-1, 10-29 
ShowControl 4-10, 4-56, 4-80, 

11 - 11 

ShowCursor 16-264 
ShowDItem 6-24, 6-62, 6-81, 6-85 
ShowHide 25-113 
ShowPen 16-265, 17-9, 17-14 
ShowWindow 25-99, 25-113, 
25-114 

shutdown routines 
Apple Desktop Bus Tool Set 
3-11 

Control Manager 4-43 
Desk Manager 5-10 
Dialog Manager 6-29 
Event Manager 7-29 
Font Manager 8-21 
Integer Math Tool Set 9-6 


LineEdit Tool Set 10-14 
List Manager 11-14 
Memory Manager 12-18 
Menu Manager 13-31 
Miscellaneous Tool Set l4-7 
Print Manager 15-27 
QuickDraw II 16-66 
QuickDraw II Auxiliary 17-7 
SANE Tool Set 18-13 
Scheduler 19-5 
Scrap Manager 20-8 
Sound Tool Set 21-9 
Standard File Operations Tool 
Set 22-17 

Text Tool Set 23-11 
Tool Locator 24-5 
Window Manager 25-33 
shutting down a tool set 2-4 
signature word 14-50 
signedFlag 9-42 
simpBRound 4-85 
simpDropSquare 4-85 
simple button 4-14 
control record 4-14-16 
simpleButton 4-86 
simpleProc 4-13, 4-15, 4-73, 

4-85 

simpRound 4-85 
simpSquare 4-85 
sine 9-23 
single mode 11-12 
size 16-43 

size box 4-4, 4-23, 4-65, 25-6, 
25-10, 25-49, 25-75 
control record 4-23-24 
SizeWindow 25-77, 25-115, 

25-125, 25-138 
slopRect 4-33-34, 4-88 
slop rectangle 4-50, 25-46 
sltlintExt 14-65 
slt2intExt 14-65 
slt3intExt 14-65 
slt4intExt 14-65 
sltSintExt 14-65 
slteintExt 14-65 
slt7intExt 14-65 
smoothing 15-7, 15-13 
sndAlreadyStrtErr 21-8, 21-37, 
B-3 


sndIntHnd 14-68 
SolidPattern 16-265 
SortList 11-8, 11-11 
SoundBootInit 21-7 
sound general logic unit 21-4 
sound hardware 21-1, 21-3-5 
sound interrupt handler 21-25 
sound procedure 6-22, 6-47 
SoundReset 21-10 
SoundShutDown 21-6, 21-9 
SoundStartUp 21-6, 21-8 
sound subsystems 21-3 
Sound Tool Set 1-4, 1-15, 21-1-37 
constants 21-36-37 
data structures 21-37 
error codes 21-37 
shutdown routine 21-9 
startup routine 21-8 
status routine 21-10 
using 21-6 

version number routine 21-9 
SoundToolStatus 21-10 
SoundVersion 21-9 
sPackageOErr 14-55, 14-70, B-1 
special character, menu 13-14-15 
special memory 12-3, 12-12, 

12-13 

specification 
connector xxvi 
language xxvii 
mechanical xxvi 
spExtra 16-30, 16-51, 16-55, 

16-58, 16-59, 16-60, 16-144, 
16-253 

spool printing 15-14-15, 15-20, 
15-23, 15-30, 15-37, 15-38, 
15-40 

square root 9-24 
SRQ list 3-3, 3-5, 3-7, 3-9, 3-15, 
3-25, 3-26, 7-24 
srqListFull 3-25, 3-29, B-4 
SRQPoll 3-25 
SRQRemove 3-26, 7-25 
stack 2-5, 5-4 
stack diagram xxix 
pseudo-type xxx 
stage byte 6-21, 6-33 
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Standard Apple Numeric 

Environment. See SANE 
standard color palette 
320 mode 16-35 
640 mode 16-36 
standard color table 16-159 
standard control type value 4-73 
Standard File Operations Tool 
Set 1-4, 1-15, 22-1-32 
constants 22-32 
data structures 22-32 
shutdown routine 22-17 
startup routine 22-16 
status routine 21-19 
using 22-13-14 
version number routine 21-18 
standard filter procedure 6-25 
standard GrafPort 16-187 
standardMenu 13-72, 13-87 
standard menu edit 5-27 
standard pen state 16-196 
standard SCB 16-145 
standard window control 25-6-7 
StartDrawing 10-11, 25-31, 25-116 
StartInfoDrawing 25-47, 25-117 
starting up a tool set 2-4 
startUpAlreadyMade 15-49, B-5 
startup order, tool set C-6 
startup routines 

Apple Desktop Bus Tool Set 
3-10 

Control Manager 4-42 
Desk Manager 5-9 
Dialog Manager 6-28 
Event Manager 7-27-28 
Font Manager 8-19-20 
Integer Math Tool Set 9-5 
LineEdit Tool Set 10-13 
List Manager 11-13 
Memory Manager 12-17 
Menu Manager 13-30 
Miscellaneous Tool Set 14-6 
Print Manager 15-26 
QuickDraw II 16-64-65 
QuickDraw II Auxiliary 17-6 
SANE Tool Set 18-12 
Scheduler 19-4 
Scrap Manager 20-7 
Sound Tool Set 21-8 


Standard File Operations Tool 
Set 22-16 

Text Tool Set 23-11 
Tool Locator 24-4 
Window Manager 25-32 
startupSlt 14-65 
St at Text 6-10, 6-12, 6-17, 6-24, 
6-88 

state record 24-18 
StatusID 14-60 
status record, printer 15-41 
status routines 

Apple Desktop Bus Tool Set 
3-12 

Control Manager 4-44 
Desk Manager 5-11 
Dialog Manager 6-30 
Event Manager 7-30 
Font Manager 8-22 
Integer Math Tool Set 9-7 
LineEdit Tool Set 10-15 
List Manager 11-15 
Memory Manager 12-20 
Menu Manager 13-32 
Miscellaneous Tool Set 14-8 
Print Manager 15-28 
QuickDraw II 16-67 
QuickDraw II Auxiliary 17-8 
SANE Tool Set 18-14 
Scheduler 19-6 
Scrap Manager 20-9 
Sound Tool Set 21-10 
Standard File Operations Tool 
Set 21-19 

Text Tool Set 23-14 
Tool Locator 24-6 
Window Manager 25-34 
StatusTextDev 23-39 
stepVector 14-68 
StillDown 7-47 

stkOvrFlwErr 14-55, 14-70, B-2 
Stop alert 6-6 
StopAlert 6-24, 6-86 
stop icon 6-86 
StopSound 21-10 
stop-sound mask 21-18-19 
StringBounds 16-29, 16-56, 16-58, 
16-266 

string bounds rectangle 16-266 


StringWidth 16-29, 16-56, 16-58, 
16-267 

structure region 25-9, 25-65, 

25-83 

stupVolMntErr 14-56, 14-70, B-2 
style 16-43 

style dialog box 15-1, 15-5-7, 

15- 45 

style subrecord 15-12-13 

SubPt 16-268 

Sup>er Hi-Res graphics mode 

16- 31, 16-155 
swap mode 21-5 
swap pair 21-5 

switch event 7-4, 7-5, 7-14, 7-46 
switchEvt 7-7, 7-50 
switchMask 7-11, 7-50 
symbol 8-4, 8-51 
synch 3-20, 3-28 
synchLayoutOrLang 3-29 
synchMode 3-29 
SynchRec 3-29 
synchRepeatDelay 3-29 
synthesizer interrupt handler 21-27 
synthModeErr 21-15, 21-37, B-3 
SysBeep 14-5, 14-53 
SysFailMgr 14-5, 14-54-56, 23-8 
sysFailMgr 14-67, 23-8 
sysField 16-146, 16-255, 16-277 
sysSpeed 14-65 
sysStrtMtErr B-2 
SystemClick 5-6, 5-26, 25-123 
system configuration 14-11 
SYSTEM directory 2-3, 5-3, 5-6, 
8-1, 8-15, 15-23, 15-24 
system direct page 5-4 
SystemEdit 5-6, 5-27, 25-123 
SystemEvent 5-28, 7-40 
system event mask 7-10, 7-45 
System Failure Manager 14-54 
system failure message 14-5, 

14-54 

system font 6-79, 8-8, 8-39, 8-40, 
8-48, 13-78, 16-147, 16-256 
System Loader 12-1, 12-14, 

12- 44, 12-45 

system menu bar 13-4-5, 13-30, 

13- 55, 13-63. 13-66, 13-68, 
13-71, 13-86 
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system speaker 14-5 
SystemTask 5-6, 5-8, 5-29, 

25-119 

system tool A-1 
system volume 21-26 
system window 5-26, 25-8, 25-66, 
25-70, 25-107 
sysTool 24-26 


T 

Tab key 6-11 
table32 0 16-274 
table640 16-274 
taliesin 8-4, 8-51 
talk 3-28 

taskInstlErr 14-48, 14-70, B-2 
task mask 25-13-14, 25-118 
taskMask bit flag 25-14 
taskMaskErr 25-118, 25-144, B-4 
TaskMaster 4-10, 5-5, 5-20, 5-26, 
5-29, 6-63, 7-12, 10-11, 13-5, 
13-7, 13-9, 13-10, 13-11, 

13-60, 13-66, 25-11, 

25-12-15, 25-21, 25-31, 

25-44, 25-64, 25-92, 
25-118-126 

taskNtFdErr 14-52, 14-70, B-2 
task record 13-10, 25-12-13, 
25-118, 25-143 
tBarColor 25-19, 25-142 
termination character 13-13 
TestControl 4-81 
testctl 4-25, 4-27, 4-86 
test file format xxvii 
text block 16-26 
TextBootInit 23-10 
TextBounds 16-29, 16-58, 16-269 
text buffer 16-54, 16-58, 16-100, 
16-157, 16-215-216 
textBufferWords l6-6l, 16-206, 
16-276 

textBufHeight l6-6l, 16-206, 
16-276 

text device 23-4, 23-15, 23-28, 

23-39 

error output 23-17, 23-18, 

23-19, 23-20, 23-21 
input 23-29, 23-30, 23-40 
output 23-41, 23-42, 23-43, 
23-44, 23-45 


text editing 6-11 
text face 16-148, 16-257 
text face flag 16-258 
text file format xxvii 
text mode 16-30, 16-149, 
16-259-260, 16-275 
TextReadBlock 23-40 
TextReset 23-13 
text Scrap 20-4, 20-19 
text screen 24-16, 24-17, 24-23 
TextShutDown 23-9, 23-11 
TextStartUp 23-5 . 23-9, 23-11 
TextStatus 23-14 
text style 16-276 
menu item 13-52 
Text Tool Set 1-4, l-l6, 23-1-47 
constants 23-46 
error codes 23-47 
shutdown routine 23-11 
startup routine 23-11 
status routine 23-14 
using 23-9 

version number routine 23-12 
TextVersion 23-12 
TextWidth 16-29, 16-58, 16-270 
TextWriteBlock 23-41 
thumb 4-8, 25-9 
thumb box 4-5 

thumbctl 4-25, 4-32-34, 4-86 

tickCnt 14-66 

TickCount 7-14, 7-48 

tick counter 14-22 

time 

ASCII 14-16 
hexadecimal 14-14, 14-15 
times 8-4, 8-51 
title, window 25-73, 25-111, 
25-115 

title bar 25-6, 25-8, 25-49 
title character 13-13 
titleColor 25-18, 25-142 
titleName 13-19, 13-20, 13-21, 
13-88 

titleParm 6-90 

titleWidth 13-19, 13-20, 13-21, 
13-88 

TLBootInit 24-4 
TLMountVoIume 24-3, 24-21-22 
TLReset 24-6 


TLShutDown 24-3, 24-5 
TLStartUp 2-1, 24-3, 24-4 
TLStatus 24-6 
TLTextMountVolume 24-3, 

24- 23-24 
TLVersion 24-5 

tmClose 25-14, 25-125, 25-140 
tmContent 25-14, 25-124, 25-140 
tmCRedraw 25-14, 25-120, 25-140 
tmDragW 25-14, 25-124, 25-140 
tmFindW 25-14, 25-121, 25-140 
tmGrow 25-14, 25-125, 25-140 
tmlnactive 13-60, 25-14, 

25- 121, 25-140 

tminfo 25-14, 25-126, 25-140 
tmMenuKey 25-14, 25-119, 25-140 
tmMenuSel 25-14, 25-121, 25-140 
tmOpenNDA 25-14, 25-122, 25-140 
tmScroll 25-14, 25-126, 25-140 
tmspecial 25-14, 25-122, 25-140 
tmSysClick 25-14, 25-123, 

25-140 

tmUpdate 25-14, 25-119, 25-140 
tmZoom 25-14, 25-125, 25-140 
toBottom 25-139 
ToDesk 25-40, 25-139 
toolErr 2-6 
toolLocl 14-67 
toolLoc2 14-67 
Tool Locator 1-2, 1-3, l-l6, 2-1, 
2-3, 24-1-26, A-2 
constants 24-26 
error codes 24-26 
shutdown routine 24-5 
startup routine 24-4 
status routine 24-6 
using 24-3 

version number routine 24-5 
toolNotFoundErr 24-7, 24-8, 

24-9, 24-10, 24-11, 24-19, 
24-20, 24-25, 24-26, B-2 
tool pointer table (TPT) 24-19, A-2 
tool set 1-1-19 

error codes 2-5, B-1-5 
installing A-6-9 
loading 2-3-4 
minimum version number 
24-10, 24-11 
RAM-based 24-3 
shutting down 2-4 
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starting up 2-4 
version information A-3 
version number A-8 
tool set dependency C-15 
tool set numbers 2-3, 24-13, A-3, 
D-1-9 

tool set startup order 2-4, C-6 
TOOLS subdirectory 2-3, 24-3, 
24-10, 24-11 

tool table 2-3, 24-11, 24-12 
toolVersionErr 24-10, 24-11, 

24- 26, B-2 
topMost 25-139 
toronto 8-4, 8-51 
TotalMem 12-46 

TPT (tool pointer table) 24-19, A-2 
traceVector 14-68 
trackball 7-21 

TrackControl 4-10, 4-82-84, 

25 - 126 

TrackGoAway 25-11, 25-125, 
25-127-128 

TrackZoom 25-11, 25-12, 25-125, 
25-129-130 

transmitADBBytes 3-21, 3-28 
transmit2ADBBytes 3-21, 3-28 
transparent 14-36, 14-67 
transparentVI 14-36, 14-67 
txFace 16-56 

txSize 16-150, 16-261, 16-277 
txtDspLang 14-65 

U 

UDivide 9-39 

unclaimedSndIntErr 21-37 
unCnctdDevErr 14-34, 14-70, B-2 
unDefHW 23-15, 23-47, B-4 
underlined menu item 13-15-16, 
13-77 

underlineMask 16-276 
underMItem 13-78, 13-87 
underscore character 2-5 
undo 5-30 

undoAction 5-7, 5-30 
UnionRect 16-271 
UnionRgn 16-272 
UnloadOneTool 22-13, 22-16, 
22-17, 24-3, 24-25 
UnloadScrap 20-17 


unlocking a memory block 12-32, 
12-33 

UnPackBytes 14-5, 14-42-44 
unrealBit 8-9, 8-10, 8-50 
unreal font 8-7, 8-8 
unsignedFlag 9-42 
unzoomed window size 25-74, 
25-112 

upArrow 4-86 
UpdateDialog 6-87 
update event 4-9, 4-54, 7-4, 7-5, 
7-14, 10-46, 25-11, 25-20, 
25-51, 25-52, 25-94, 25-95, 
25-96 

updateEvt 7-7, 7-50, 25-119 
updateMask 7-11, 7-50 
update region 6-87, 10-39, 25-35, 
25-67, 25-80, 25-81, 25-131, 
25-132 

upFlag 4-22, 4-72, 4-85 
userCtlitem 6-10, 6-12, 6-88 
userCtlltemZ 6-10, 6-12, 6-88 
userField 16-151, 1^262, 16-277 
user ID 2-1, 2-2, 5-4, 12-10, 

12-14, 12-15, 12-17, 12-18, 
12-35, 14-57, 14-59, 14-60 
master 12-10-11, 12-14, 12-15, 
12-23, 12-35 

User ID Manager 12-10, 12-14, 
12-17, 14-6, 14-57 
user Item 6-10, 6-11, 6-12, 6-88 
user tool A-1, A-6 
userTool 24-26 
user tool set A-6 
userVolume 14-65 
usrTLocl 14-67 
usrTLoc2 14-67 

V 

ValidRect 25-131 

ValidRgn 6-87, 25-132 

varCode parameters 25-25 

vAxisOnly 4-53, 4-86 

vbint 14-24, 14-66 

vblDi sable 14-26, 14-67 

vblEnable 14-26, 14-67 

VBL interrupt 14-27, 14-49 

vblIntHnd 14-68 

vector address 14-5, 14-61, 14-63 


vector reference number 14-62 
Venice 8-4, 8-51 
version 16-42, 16-43 
version information A-3 
version number A-8 
font definition 16-42, 16-43 
minimum 24-10, 24-11 
version number routines 
Apple Desktop Bus Tool Set 
3-11 

Control Manager 4-43 
Desk Manager 5-10 
Dialog Manager 6-29 
Event Manager 7-29 
Font Manager 8-21 
Integer Math Tool Set 9-6 
LineEdit Tool Set 10-14 
List Manager 11-14 
Memory Manager 12-19 
Menu Manager 13-31 
Miscellaneous Tool Set 14-7 
Print Manager 15-27 
QuickDraw II 16-66 
QuickDraw II Auxiliary 17-7 
SANE Tool Set 18-13 
Scheduler 19-5 
Scrap Manager 20-8 
Sound Tool Set 21-9 
Standard File Operations Tool 
Set 22-18 

Text Tool Set 23-12 
Tool Locator 24-5 
Window Manager 25-33 
view rectangle 6-17, 10-4, 10-6-7, 
10-11, 10-17, 10-30 
visible region 16-14-15, 16-17, 
16-152, 16-153, 16-187, 

16- 197, 16-208, 16-264, 

17- 10, 25-35, 25-47 
visRgn 16-15, 16-152, 16-263, 

25-23, 25-28 
volSetting 21-17, 21-37 
volume setting 21-21, 21-26 
vSizing 15-12, 15-13, 15-48 

W 

WaitCursor 17-5, 17-16 
WaitMouseUp 7-14,7-49 
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WAPT (work area pointer table) 

A-4, A-10 

waveSize 21-17, 21-37 
waveStart 21-17, 21-37 
wCalcRgns 25-25, 25-140 
wCalledSysEdit 25-123, 25-140 
wClickCalled 25-123, 25-140 
wClosedNDA 25-122, 25-140 
wColor 25-84, 25-87, 25-142 
wContDefProc 25-21, 25-26, 

25-84, 25-88, 25-119, 25-143 
wContRgn 25-16, 25-142 
wControls 25-16, 25-142 
wDataH 25-84, 25-87, 25-142 
wDataV 25-84, 25-87, 25-142 
wDev 15-12. 15-13, 15-48 
wDispose 25-25, 25-140 
wDraw 25-25, 25-140 
wDrawFrame 25-27 
wedge 16-24 

wFrameBits 25-21, 25-69, 25-84, 
25-85, 25-108, 25-142 
wFrameCtrls 25-16, 25-142 
wFrameDefProc 25-25, 25-84, 
25-88, 25-143 
wGrow 25-25 
what 7-6, 7-7, 7-43, 7-51 
wHAxisOnly 25-139 
when 7-6, 7-14, 7-43, 7-51, 13-61, 
13-66 

where 7-6, 7-38, 7-43, 7-51 
wHit 25-25, 25-140 
white 16-275 
wHitFrame 25-126 
widMax 16-56, 16-62, 16-226 
widMaxSize 16-226, 16-274 
width 16-13, 16-277 
wInactMenu 13-60, 25-49, 

25-121, 25-140 

wInContent 25-11, 25-12, 25-28, 
25-49, 25-124, 25-140 
WindBootInit 25-32 
WindDragRect 25-133-134 
wInDesk 25-49, 25-140 
wInDeskItem 25-49, 25-122, 
25-140 

WindNewRes 25-135 


window 25-1 

alert 6-7, 25-6, 25-17 
application 25-8, 25-66, 25-70 
control 4-8 
dialog 6-7 

document 25-6, 25-17 
system 5-26, 25-8, 25-66, 

25-70, 25-107 
window colors 25-17-20 
window color table 25-142 
window controls 25-6-7 
window definition procedure 25-20, 
25-25, 25-55, 25-58, 25-98, 
25-101, 25-127 
window frame 25-17, 25-20, 

25-108, 25-115 

window frame color 25-18, 25-57, 
25-99 

window frame scroll bars 25-62, 
25-64, 25-96, 25-105, 25-106 
window frame type 25-69, 
25-84-85, 25-108 
WindowGlobal 25-136-137 
window global flag 25-136-137 
window global mask 25-137 
window information bar 25-20 
Window Manager 1-3, 1-17-19, 

13-7, 13-64, 13-66, 25-1-144 
constants 25-139-141 
data structures 25-142-143 
error codes 25-144 
icon font 25-15, 25-109 
shutdown routine 25-33 
startup routine 25-32 
status routine 25-34 
using 25-10-11 
version number routine 25-33 
window menu bar 13-5 
window origin 25-29 
window record 25-15-16, 25-88, 
25-142 

window size box 25-19 
window title 25-73, 25-111, 25-115 
window title bar color 25-19 
window title color 25-18 
wInDrag 25-11, 25-28, 25-49, 
25-124, 25-140 
WindReset 25-34 


WindShutDown 25-11, 25-33 
windSize 25-141 
WindStartUp 25-11, 25-32 
WindStatus 25-34 
WindVersion 25-33 
wInfoDefProc 25-84, 25-88, 

25-143 

wInfoHeight 25-21, 25-84, 25-88, 
25-143 

wInfoRefCon 25-59, 25-84, 25-88, 
25-143 

wInFrame 25-28, 25-49, 25-126, 
25-140 

wInGoAway 25-11, 25-27, 25-28, 
25-49, 25-125, 25-140 
wInGrow 25-11, 25-28, 25-49, 
25-125, 25-140 

win Info 25-28, 25-49, 25-126, 
25-140 

wInMenuBar 13-10, 25-11, 25-49, 
25-121, 25-123, 25-140 
wInSpecial 25-49, 25-122, 
25-123, 25-140 
wInSysWindow 25-49, 25-140 
wInZoom 25-11, 25-27, 25-28, 
25-49, 25-125, 25-140 
wMaxH 25-84, 25-87, 25-142 
wMaxV 25-84, 25-87, 25-142 
wmNotStartedUp 4-42, 4-48, 

4-88, B-4 

wmTaskMaskErr 25-119 
wmTaskRecSize 25-141 
wNew 25-25, 25-140 
wNext 25-16, 25-142 
wNoConstraint 25-139 
wNoHit 25-28, 25-49 
work area pointer table (WAPT) 

A-4, A-10 

wPadding 25-16, 25-142 
wPageHor 25-84, 25-88, 25-143 
wPageVar 25-84, 25-88, 25-143 
wPlane 25-84, 25-88, 25-143 
wPosition 25-84, 25-88, 25-143 
wRefCon 25-38, 25-72, 25-84, 
25-87, 25-110, 25-142 
WriteBParam 14-4, 14-11-12, 
14-13 
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WriteBRam 14-4, 14-9 
WriteChar 23-42 
WriteCString 23-7, 23-43 
WriteLine 23-44 
writeMicroMem 3-20, 3-28 
write next 21-23, 21-34 
writeNext 21-23, 21-36 
writeProtected 23-16, 23-47, 
B-4 

Write RAM 21-23, 21-32 
writeRAM 21-23, 21-36 
WriteRamBlock 21-28 
Write Register 21-23, 21-30 
writeRegister 21-23, 21-36 
WriteString 23-45 
WriteTimeHex 14-4, 14-15 
wScrollHor 25-84, 25-87, 25-143 
wScrollVer 25-84, 25-87, 25-143 
wStorage 25-84, 25-88, 25-143 
wStructRgn 25-16, 25-142 
wTitle 25-84, 25-85, 25-142 
wTrackZoom 25-125 
wUpdateRgn 25-16, 25-142 
wVAxisOnly 25-139 
wXOngin 25-84, 25-87, 25-142 
wYOrigin 25-84, 25-87, 25-142 
wZoom 25-84, 25-87 


X 

xDivide 3-24, 3-29 
xMultiply 3-24, 3-29 
xOffset 3-24, 3-29 
xorMItemHilite 13-78, 13-87 
XorRgn 16-273 
xorTitleHilite 13-72 
X2Fix 9-40 
X2Frac 9-41 
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yDivide 3-24, 3-29 
yellow 16-275 
yMultiply 3-24, 3-29 
yOffset 3-24, 3-29 
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ZeroScrap 20-5, 20-6, 20-11, 
20-16, 20-18 

zeroSize 16-226, 16-274 
2cx>m box 25-6, 25-10, 25-49 
zoomed window size 25-74, 
25-112 

zoom region 25-9, 25-11, 25-49, 
25-129-130 

ZoomWindow 25-11, 25-12, 
25-138 
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